Handleiding-Decentrale-Validatie-Service.md

+# 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 in onderstaande tabel zien.
+
+| iStandaard | Huidige versie | Versie in ontwikkeling |
+| ------ | ------ | ------ |
+| iWlz | 2.1 |  |
+| iWmo | 2.4 | 3.0 |
+| iJw | 2.4 | 3.0 |
+| iPgb | 2.0 |  |
+| iEb | 1.0 |  |	
+
+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](https://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](https://istandaarden.nl/modules) 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
+```
+
+ 
+![Starten_van_de_DVS_1](uploads/acb29bd00dd1408b94608b8a0f490890/Starten_van_de_DVS_1.png)
+
+![Starten_van_de_DVS_2](uploads/90ab24aced92c399d2f28bdb0289661e/Starten_van_de_DVS_2.png)
+ 
+
+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
+```
+
+![Starten_van_Docker](uploads/8b655752542a94d4268639914c4239e3/Starten_van_Docker.png) 
+
+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. 
+
+### 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:
+
+![Controleren_van_de_status](uploads/cd2259f39cefb4a9db73a4afe974969c/Controleren_van_de_status.png)   
+
+## 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
+```
+De respons is een rapport.
+
+![valideren_van_een_bericht](uploads/ba902c6fec4814f0752b61bfaf49a360/valideren_van_een_bericht.png) 
+
+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
+```
+De response is het complete retourbericht
+
+![Het_genereren_van_een_retourbericht](uploads/c055af6786647a92670853ae1bb7bf02/Het_genereren_van_een_retourbericht.png) 
+
+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:
+
+
+| Foutcode  | Betekenis |
+| ------ | ------ |
+|  200   | Het heenbericht is technisch in orde, zie de respons voor functionele fouten |
+|  404   | Ongeldig verzoek, verzoek gebruikt de verkeerde HTTP methode of wordt gedaan op de verkeerde resource | 
+|  406   | Ongeldig verzoek, het verzonden bericht kom niet overeen met een bekend schema. (Dit kan komen door een niet ondersteund type bericht of door een technische fout in het bericht) | 
+|  411   | Ongeldig verzoek, de Content-Length header ontbreekt | 
+|  415   | Ongeldig verzoek, het Content-Type moet ‘application/x-www-form-urlencoded’ zijn |
+|  500   | Er is een fout opgestreden in de DVS |
+