Developer Guide MO VZVZ
- Helma van der Linden
- Tjerk Drouen
Table of Contents
- 1 Table of Contents
- 2 Version
- 2.1 Changelog
- 2.1.1 Version 0.0.1
- 2.1 Changelog
- 3 Introduction
- 3.1 Purpose
- 3.2 Scope
- 3.3 Intended audience
- 3.4 References
- 3.4.1 Glossary
- 4 Product Overview
- 5 Related documents
- 6 Architecture
- 6.1 Context
- 6.2 Context diagram
- 6.3 Flow chart
- 6.3.1 Algemene workflow uitwisseling
- 6.3.1.1 Opvragen medicatiegegevens
- 6.3.1.1.1 Workflow
- 6.3.1.1.2 Interacties
- 6.3.1.1.3 Berichten
- 6.3.1.2 Sturen en afhandelen medicatievoorschrift
- 6.3.1.3 Sturen en afhandelen medicatiegegevens
- 6.3.1.1 Opvragen medicatiegegevens
- 6.3.1 Algemene workflow uitwisseling
- 6.4 Use cases
- 6.4.1 Which use cases should I support
- 6.4.2 Individual use cases
- 6.4.2.1 MP-MGR MP-MGB proxy-facade
- 6.4.2.2 MP-MGR MP-MGB FHIR includes
- 6.4.2.3 Patient identifier not part of argument but part of context
- 6.4.2.4 MP-VOS + LAB-LRS
- 6.4.2.5 Security
- 6.4.2.6 HTTP-Headers
- 6.4.2.7 AoF FHIR Search parameter support for generic query using get-aorta-data
- 6.4.3 Provenance Resources in FHIR response bundles
- 6.5 Sequence diagrams
- 6.6 Class diagrams
- 7 Available APIs
- 8 Security
- 9 Configuration
- 10 Common Issues/Known Issues
- 11 Contact information
Dit is een sjabloon voor de Developer Guide. Alle instructies staan in een Note panel (paars). Voorbeelden worden cursief weergegeven.
De instructies worden in het Nederlands gegeven, maar de uiteindelijke tekst van de Developer Guide is in het Engels. Engels is Amerikaans Engels.
Version
Deze sectie bevat informatie over het document zelf. Zoals versie informatie en een change log
Date | Status | Version | Remarks | Author(s) |
|---|---|---|---|---|
|
|
|
|
|
| Draft | 0.0.1 | First draft | VZVZ |
| Draft | 0.0.1 | Added essential information on VZVZ deviations from Nictiz specs Added TODOs Added reference links | |
| v1 | 1.0 | Aanpassingen nictiz URLs | |
|
|
| Added paragraph 'Dataset constraints are transaction specific' |
Changelog
Beschrijf globaal in het Engels wat er in deze versie is veranderd t.o.v. de vorige versie.
Hanteer de volgende indeling:
H3 kopje ‘Version’ gevolgd door het versienummer
H4 kopje ‘Fixed’ met daaronder als bullet list voor elke fix het Jira issue nummer dat geleid heeft tot deze fix en daar achter een korte omschrijving van de fix
H4 kopje ‘New’ met daaronder als bullet list voor elke nieuwe toevoeging het Jira issue nummer dat geleid heeft tot deze toevoeging en daar achter een korte omschrijving van de toevoeging
Version 0.0.1
First draft
Introduction
Purpose
Korte beschrijving van de scope van dit document.
The purpose of this document is to support the implementation of the Healthcare Application Medicatieoverdracht on the AORTA-LSP infrastructure.
Scope
Platte tekst, dus geen verwijzing.
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.
Platte tekst, dus geen verwijzing.
Formuleer hier in de template een standaard tekst, omdat de doelgroep voor een dev guide bijna altijd hetzelfde is. Zie voorstel hierboven.
References
Glossary
Hier komt een tabel met Nederlandse en Engelse termen met uitleg. Onderstaande tabel kan gebruikt en aangevuld worden met specifieke termen die in deze Developer Guide gebruikt worden.
- TODO de termen en de omschrijvingen moeten nog gecontroleerd worden op correctheid.
- TODO termen en omschrijvingen aanvullen met MO-specifieke termen cq verwijzen naar beschrijvingen van die termen
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:
|
Product Overview
Requirements (Programma van eisen)
The list of requirements for the healthcare application addressed in this Developer Guide can be found here:
verwijzing naar de betreffende PvE → inline link
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.
Functioneel Ontwerp Medicatieproces 9 versie 3.0.0-beta.4 - informatiestandaarden
Functional Design Medication Process 9 version 3.0.0-beta.4 English version - informatiestandaarden
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.
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 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 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
FHIR profiles:
Voorbeelden: Nictiz R4 MedicationProcess - SIMPLIFIER.NET
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.
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.
Dataset constraints are transaction specific
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 under: Dataset: mp- DECOR-samenvatting (Data Elements, Codes, OID's en Rules) in the ZorgView column!
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) |
|---|---|---|---|---|
PatientIdentificationNumber | Search on patient. |
|
| NOT supported on argument line is part of context |
Identification | Search on identifier. |
| GET [base]/MedicationRequest?identifier=http://example.nl/fhir/NamingSystem/MedicationRequest|999922448 | Supported via GET [base] $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. |
| GET [base]/MedicationRequest?pharmaceutical-treatment-identifier=http://example.nl/fhir/NamingSystem/pharmaceuticaltreatment|1247848 | Supported via GET [base] $get-aorta-data? &therapy-identifier=<http://example.nl/fhir/NamingSystem/pharmaceuticaltreatment|<id> |
Type | Search on type of medication building block. |
| Retrieves all MedicationRequest resources that represent the building block MedicationAgreement. GET [base]/MedicationRequest?category=http://snomed.info/sct|33633005Retrieves all MedicationRequest resources that represent the building block DispenseRequest. Retrieves all MedicationRequest resources that represent the building block VariableDosingRegimen.
| Supported via GET [base] 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. |
|
| 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. |
|
| Supported via effective-time as GebruiksPeriode GET [base] |
DispensePeriod | Returns all medication dispenses within the specified time period. |
|
| Supported via effective-time as VerstrekkingsPeriode GET [base] |
AdministrationPeriod | Returns all medication administrations within the specified time period. |
|
| Supported via effective-time as ToedieningsPeriode GET [base] |
- | 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. |
|
| 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 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:
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
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/91984074
Class diagrams
Zie https://vzvz.atlassian.net/wiki/spaces/ZM/pages/1155367293
Zie ook Architectuur
Available APIs
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 |
|---|---|
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 Programma van Eisen.
Encryption
See requirements in Programma van Eisen.
Authentication
Zie Autorisatierichtlijn Medicatieveiligheid | AORTA-LSP.
See requirements in Programma van Eisen.
See Architectuur; Actors
Configuration
Common Issues/Known Issues
Contact information
Person | Role/Type of questions | Contact |
|---|---|---|
Bart Molenaar | Product Manager | - |
VZVZ Testteam |
| |
VZVZ Architects |
|