Handleiding Decentrale Validatie Service

Over de Decentrale Validatie Service

De Decentrale Validatie Service (DVS) biedt alle gebruikers van het iStandaarden-berichtenverkeer de mogelijkheid de iStandaarden-berichten die zij gebruiken te valideren.

De DVS maakt het mogelijk de validatie van iStandaarden-berichten uit te voeren in een interne (eigen) softwareomgeving. Dit maakt de service geschikt om toe te passen bij het valideren van productiegegevens.

De DVS werkt met alle berichten (heen en retour) die gespecificeerd zijn in de Informatiemodellen iStandaarden . In de regel ondersteunt de module de iStandaard Release versie die momenteel in gebruik of productie is en de in ontwikkeling zijnde release van een iStandaard. Een actueel overzicht van de ondersteunde releases kunt u hier vinden.

De declaratieberichten AW319 en AW320 (iWlz) kunt u valideren met het Portaal voor testbestanden Externe-Integratiestandaarden (PORTES) van Vektis.

Controle StUF-envelop

Bij gebruik van een StUF-envelop voor iWmo- of iJw-berichten voert de DVS een afzonderlijke controle uit van de envelop. De validatie houdt in dat de geldigheid ten opzichte van de actuele schemadefinitie nagegaan wordt. Als die in orde is, dan voert de module een inhoudelijke controle uit van het iStandaard-bericht.

Controle door de Decentrale Validatieservice

De DVS stelt het type iStandaard-bericht vast en controleert de berichten inhoudelijk op structuur, vulling en alle gespecificeerde technische regels, condities en constraints. De module controleert geen berichtoverstijgende regels.

Deze handleiding beschrijft de installatiewijze en alle functionaliteiten van de DVS.

Meer informatie

Hebt u vragen over het gebruik of installatie van de Decentrale Validatieservice? Neemt u dan contact op met:

Zorginstituut Nederland
Team Informatiestandaarden
(020) 797 89 48
info@istandaarden.nl
www.istandaarden.nl

Toegang tot de Decentrale Validatie Service

Het is niet nodig om een iStandaarden-account aan te vragen om de service te gebruiken.

Docker container

Zorginstituut Nederland stelt de DVS via haar eigen registry en repository beschikbaar in de vorm van een Docker image. Dit betekent dat de service uitgevoerd wordt in een Docker container.

Meerdere containers kunnen op dezelfde computer worden uitgevoerd, die elk als geïsoleerde processen naast elkaar bestaan. Docker containers kunnen zowel binnen Windows, Linux als MacOs omgevingen gebruikt worden.

Benodigde programmatuur

Omdat de DVS binnen een Docker container draait is het noodzakelijk dat de daarvoor benodigde programmatuur aanwezig is op de omgeving waar de container wordt gebruikt. De benodigde software kan gevonden worden op de volgende locatie: https://www.docker.com/get-started.

Altijd de juiste versie

Bij het starten van de service controleert de Decentrale Validatieservice automatisch of nieuwe updates zijn uitgevoerd in de XSD’s en XSLT’s van de iStandaarden. Het is niet meer nodig om na een update van de iStandaarden een nieuwe installatie uit te voeren. Een service die continu draait binnen een omgeving zal eens per dag de update ophalen, het is dus ook niet nodig deze te herstarten.

De module pagina op istandaarden.nl biedt te allen tijde een compleet en actueel overzicht van alle beschikbare bestanden en documentatie bij de DVS.

Het uitvoeren van validatie

Validatie wordt uitgevoerd met behulp van een eenvoudige web-service die geen gebruikersauthenticatie of geavanceerde invoervalidatie biedt. Er is een eenvoudig shell-script aanwezig om de opstart- / uitschakeltijden te minimaliseren en de afbeeldingsgrootte van de Docker container te verkleinen. De service is als zodanig ook niet bedoeld om op het publieke internet aan te sluiten en zou alleen berichten moeten ontvangen van vertrouwde applicaties.

Retourberichten Genereren

Een retourbericht wordt gegenereerd op basis van het ontvangen bericht waarop een aantal bewerking worden uitgevoerd op basis van de gebruikte standaarden en regels. Ook wordt een validatie gedaan op basis van de geldende regels en worden alle ontdekte fouten toegevoegd in het retourbericht.

Installatie van de service op een omgeving

De DVS is beschikbaar gesteld via de iStandaarden repository als Docker image, en is te vinden op: https://repository.istandaarden.nl.

Starten van de DVS

De Docker container kan worden opgehaald van de ZiN servers met het volgende commando:

docker pull registry.istandaarden.nl/modules/dvs:<versie>

Voor altijd de meest recente versie ophalen:

docker pull registry.istandaarden.nl/modules/dvs:latest

Als er een specifieke versie gestart wordt:

docker run -itp 8080:8080 registry.istandaarden.nl/modules/dvs:<versie>

Als de meest recente versie gestart wordt:

docker run -itp 8080:8080 registry.istandaarden.nl/modules/dvs:latest

Dit zal de container starten waarna de applicatie bereikt kan worden op poort 8080 Bij het opstarten worden automatisch de meest recente versie van de standaarden gedownload als er een internetverbinding beschikbaar is. Daarnaast wordt in een continu draaiende container elke dag om 03:00 de laatste versie van de standaarden opgehaald.

Alle verzoeken moeten een Content-Type header bevatten met de waarde application/x-www-form-urlencoded en een correcte Content-Length header.

Vanaf versie 1.1: ondersteunen aanroepen een X-Version-Override header waarmee het patchniveau van de standaard kan worden overschreven. Als deze waarde niet in het verzoek aanwezig is, wordt de standaard patch versie gebruikt (welke overeen komt met de validatiedatum, niet met de dagtekening). Als het gevraagde patchniveau niet of niet langer wordt ondersteund, wordt een foutcode 400 geretourneerd.

Let op:

Automatische updates kunnen patchniveaus introduceren en verwijderen, dus de software die de aanroep doet zou een zinvolle standaard behandeling moeten hebben voor niet-ondersteunde patchniveaus.

Controleren van de status van de applicatie

Ten behoeve van het beheer van de DVS en integratie met systemen die ervoor zorgen dat deze ten alle tijden beschikbaar is kan de status van de applicatie opgevraagd worden via de /status resource.

Deze aanroep kan op de volgende manier gedaan worden:

curl <host>:8080/status

Een voorbeeld voor als de DVS op een lokale machine draait is dan:

curl localhost:8080/status

Deze aanroep leidt bij een naar behoren functionerend programma tot de volgende respons:

Het gebruik van de module

Aan de hand van voorbeelden beschrijven we hoe u met de DVS kunt werken om uw berichten te valideren.

Het valideren van een bericht

Een bericht dat gevalideerd moet worden kan op de volgende wijze aangeboden worden aan de DVS via een POST bericht naar de /validatie resource van de applicatie. Het te valideren bericht wordt in dit geval meegestuurd in de body van het POST bericht.

De aanroep kan op de volgende manier gedaan worden:

curl -X POST --data-binary @<path>bericht.xml <host>:8080/validatie

De volgende opties zijn ook handig om te gebruiken bij curl:

-v, verbose, toont uitgebreidere informatie over de aanroep die met curl gedaan wordt

-i, include, toont de headers in de output

Als er een fout zit in de header of in de structuur van het bericht dan zal je error alleen zien als je deze opties gebruikt.

Een voorbeeld voor als de DVS op een lokale machine draait is:

curl -X POST –i –v --data-binary @bericht.xml localhost:8080/validatie

Voorbeeld voor validatie met iWmo 3.0.4 voor DVS 1.1.0 en nieuwer: (geldig vanaf 22-07-2021 tot 1-09-2021)

curl -X POST -H "X-Version-Override: 3.0.4" --data-binary @bericht.xml localhost:8080/validatie

De respons is een rapport.

Als de aanroep via een andere applicatie of service gebeurd gelden de volgende specificaties voor de aanroep:

Endpoint: <host>:8080/validatie

Method: POST

Required Headers:

• Content-Type : application/x-www-form-urlencoded
• Content-Length : <content length>

Het genereren van een retourbericht

Voor het genereren van een retourbericht kan de /retour resource van de applicatie aangeroepen worden met het heenbericht waarvoor het retourbericht gegenereerd moet worden. Het heenbericht wordt meegestuurd in de body van het POST bericht dat naar de service wordt gestuurd.

De aanroep kan op de volgende manier gedaan worden:

curl -X POST --data-binary @heenbericht.xml <host>:8080/retour

Een voorbeeld voor als de DVS op een lokale machine draait is:

curl -X POST --data-binary @heenbericht.xml localhost:8080/retour

Voorbeeld voor validatie met iWmo 3.0.4 voor DVS 1.1.0 en nieuwer: (geldig vanaf 22-07-2021 tot 1-09-2021)

curl -X POST -H "X-Version-Override: 3.0.4" --data-binary @heenbericht.xml localhost:8080/retour

De response is het complete retourbericht

Als de aanroep via een andere applicatie of service gebeurt, gelden de volgende specificaties voor de aanroep:

Endpoint: <host>:8080/retour

Method: POST

Required Headers:

• Content-Type : application/x-www-form-urlencoded
• Content-Length : <content length>

Foutcodes

Mocht er bij het aanroepen van de DVS wat fout gaan, of als de DVS het bericht niet kan verwerken, dan zal de DVS reageren met de één van de volgende foutcodes:

Bijlage iWmo en iJw

Voor de iWmo en iJw resulteert dit in de volgende services: De reactie van de DVS is afhankelijk van het verzoek aan de DVS en het bericht. Voor ieder bericht kan een validatie worden uitgevoerd. Afhankelijk van het soort bericht is dit tegen de XSD of zowel XSD als XSLT. Indien er in de iStandaard een retourbericht is gedefinieerd op een heenbericht, kan de DVS ook een retourbericht genereren. In onderstaande tabel kunt u zien wat de reactie van de DVS is afhankelijk van het verzoek.