Koppelvlakspecificatie GGK/RINIS/VSP iWmo-berichtenverkeer
Project iWmo Ton Monasso Versie 1.0 8 oktober 2014
1
Inleiding Dit document beschrijft de specificaties van de elektronische uitwisseling van iWmo-berichten tussen de knooppunten voor Wmo-aanbieders (VECOZO Schakelpunt, VSP) en gemeenten (Gemeentelijk Gegevensknooppunt, beheerd door het Inlichtingenbureau) met RINIS als intermediërend knooppunt. Deze drie knooppunten maken deel uit van een keten die begint en eindigt bij gemeenten en aanbieders. Die partijen noemen we in dit document ook wel “eindafnemers”. Eventuele schakels in de keten voor of na de deelketen VECOZO-RINIS-IB v.v. maken geen deel uit van dit document. De koppelvlakspecificatie is bedoeld als een gezamenlijke beschrijving van de gegevensstromen en de belangrijkste operationele afspraken tussen de knooppunten. Het geeft daarmee richting aan de ontwikkeling of aanpassing van de knooppunten, biedt houvast voor de Afhankelijkheden & Kwetsbaarheden-analyse en de ketentest, kan worden gebruikt voor het vormgeven van SLA’s en is input voor de Projecteindarchitectuur (PEA). Dit document beschrijft niet de technische en organisatorische beveiligingsmaatregelen die de knooppunten moeten nemen, noch de bestuurlijke, organisatorische of juridische verantwoordelijkheidsverdeling. Het is gericht op een functionele en technische beschrijving van de rol die de knooppunten naar elkaar vervullen, ten dienste van een goed functionerende berichtenstroom. De werking van de functies van de knooppunten zelf valt buiten scope van dit document; er wordt vanuit gegaan dat de knooppunten afdoende maatregelen hebben genomen om de kwaliteit van hun eigen operatie te waarborgen. Uitgangspunt voor de koppelvlakspecificatie is dat er zoveel mogelijk wordt uitgegaan van bestaande functionaliteit omdat hergebruik van bestaande middelen uitgangspunt is van het project. We gaan uit van een situatie waarin de knooppunten de berichten WMO301 t/m WMO304 versie 1.01 met elkaar kunnen uitwisselen. VECOZO en Inlichtingenbureau (IB) hebben geen rechtstreekse koppeling, maar wisselen gegevens uit via RINIS. De koppelvlakspecificaties zijn tot stand gekomen in nauwe samenwerking tussen de betrokken partijen (VWS/iWmo, VNG/KING, VECOZO, IB en RINIS) en zijn vastgesteld in het ketenoverleg d.d. 30 september 2014.
Taak van de knooppunten De knooppunten hebben de volgende functies: VECOZO Schakelpunt: o Het doorsturen van de van aanbieders ontvangen berichten WMO302 en WMO303 aan het GGK, voor zover de berichten technisch correct zijn. o Het afleveren van via RINIS ontvangen berichten WMO301 en WMO304 aan aangesloten aanbieders, voor zover de berichten technisch correct zijn. o Het controleren van de inhoud van de berichten WMO301 t/m WMO304 die het VSP passeren op basis van de controleregels zoals die zijn aangeleverd door Zorginstituut Nederland en Vektis, en - afhankelijk van de uitkomsten van de controle - het doorsturen van de berichten naar de ontvanger danwel het genereren van een retourbericht aan de verzender. In het geval een controle op een retourbestand 1
De specificaties zoals gepubliceerd door Zorginstituut Nederland (WMO301 en WMO302) en Vektis (WMO303 en WMO304) zijn leidend. Gepubliceerde correcties binnen versie 1.0 tellen als onderdeel van de standaard.
2
resulteert in een afkeuring van het retourbestand, dan zal IB respectievelijk de aanbieder daarvan op de hoogte worden gebracht2. Gemeentelijk Gegevensknooppunt: o Het afleveren van via RINIS ontvangen berichten WMO302 en WMO303 aan aangesloten gemeenten. o Het via RINIS doorsturen van de van gemeenten ontvangen berichten WMO301 en WMO304 aan het VSP. RINIS: o Het doorsturen van berichten van de typen WMO301 en WMO304, afkomstig van het GGK, aan het VSP. o Het doorsturen van berichten van de typen WMO302 en WMO303, afkomstig van het VSP, aan het GGK. o In beide gevallen: het vertalen van de GGS-envelop in een bestandsstructuur en vice versa.
Bij het doorsturen van berichten dragen de knooppunten zorg voor het toepassen van de kwaliteitscontroles, die verderop zijn beschreven. De knooppunten moeten op verzoek van de naburige knooppunten in staat zijn om berichten die binnen de bewaartermijn vallen, opnieuw te verzenden. De precieze procedure voor herzending wordt uitgewerkt in nadere operationele beheerafspraken.
Opslag van berichten Met “doorsturen” bedoelen we in alle gevallen asynchroon berichtenverkeer volgens het store-andforwardprincipe: een bericht wordt in beginsel pas verwijderd als het succesvol is opgehaald of afgeleverd door het volgende knooppunt of door de gemeente/aanbieder. Met een dergelijke serie van betrouwbare overdrachten wordt gegarandeerde aflevering bewerkstelligd. Voor de bewaartermijnen van de iWmo-berichten zelf (WMO301 t/m WMO304), hanteren de knooppunten een termijn van 30 dagen (720 uur). Dit betreft alle situaties en is daarmee onafhankelijk van het feit of een bericht wel of niet succesvol is afgeleverd/opgehaald bij de volgende schakel (knooppunt danwel eindafnemer). De knooppunten bewaren metadata van het bericht gedurende minimaal en maximaal 1 jaar na de laatste mutatie van een berichtstatus. Deze dataset bestaat bij alle knooppunten ten minste uit: Het type bericht (bijv. WMO301) De functionele verzender (gemeentecode danwel AGB-code) De functionele ontvanger (gemeentecode danwel AGB-code) Het referentienummer van het iWmo-bericht Het crossreferentienummer van het iWmo-bericht (in het geval van WMO302 en WMO304) Een timestamp van het moment dat het bericht door het knooppunt is ontvangen Een timestamp van het moment dat het bericht succesvol is afgeleverd bij of opgehaald door het volgende knooppunt of de eindafnemer (indien van toepassing) Een timestamp van het moment dat het bericht door het knooppunt is verwijderd 2
IB per e-mail. De aanbieder via een webservice voor statusmeldingen (indien hij daar gebruik van maakt), anders per e-mail.
3
Bij een timestamp worden ten minste opgeslagen: jaar, maand, dag, uur, minuut en seconde. Ook moet de tijdzone en het al dan niet gebruiken van daylight savings time herleidbaar zijn. Kloksynchronisatie is een vereiste. Eventuele door de knooppunten gegenereerde foutberichten (e-mailberichten of terugkoppelingen via een webportaal of webservice; niet zijnde retourberichten) worden ten minste 30 dagen en maximaal een jaar bewaard. De bron van de te bewaren metadata (bijvoorbeeld de envelop, het iWmo-bericht zelf of uit de interface met de eindafnemer) kan door het knooppunt worden bepaald, zolang wordt voldaan aan de minimale metadataset. Ten behoeve van tracking & tracing is met deze metadataset voor de meeste berichten uniek te identificeren of zij zich op het knooppunt bevinden of hebben bevonden, en (indien van toepassing) of ze succesvol zijn verzonden naar een naburig knooppunt. De sleutels zijn: Berichttype3 WMO301 WMO302 WMO303 WMO304
Velden uit het iWmo-bericht Gemeentecode, Identificatie heenbericht Wmo Aanbieder, Identificatie retourbericht Code Wmo-aanbieder, Factuurnummer Code Wmo-aanbieder, Factuurnummer
In de volgende voorziene situaties is unieke identificatie van een bericht niet mogelijk: De oorspronkelijke verzender voldoet niet aan de uniciteitsvereisten voor het vullen van de sleutelvelden. Het factuurnummer is niet uniek in combinatie met “Code Wmo-aanbieder”. De berichtspecificaties van WMO303 en WMO304 schrijven voor dat het Factuurnummer uniek moet zijn voor de partij aan wie de betaling moet worden verricht. Wanneer deze partij verandert, bestaat de kans dat de combinatie van Factuurnummer en “Code Wmoaanbieder” niet uniek is.
Kwaliteitseisen aan de berichten Onderstaande kwaliteitsgaranties worden naar elkaar afgegeven door de knooppunten, op het niveau van de 'envelop'/het transport. Wanneer een bericht hieraan niet voldoet, is het verzendende knooppunt verantwoordelijk voor het corrigeren en heraanbieden van het oorspronkelijke bericht (als de fout te wijten is aan het knooppunt én herstelbaar is) danwel notificeren van de oorspronkelijke verzender (als de fout te wijten is aan die verzender of de fout niet herstelbaar is en geen valide bericht kan worden aangeboden).
Berichten van IB naar RINIS
3 4
Voldoen aan de GGS-standaard4 Hebben betrekking op een type iWmo-bericht waarvoor een ketenoperatie bestaat (bijv. Toewijzing en Declaratie)
Het berichttype zelf maakt ook onderdeel uit van de sleutel. De specificatie is bijgevoegd.
4
Zijn verzonden door een partij die de in het iWmo-bericht vermelde gemeentecode mag gebruiken (conform de autorisatieregels van het IB)
Berichten van RINIS aan VECOZO
Hanteren voor het iWmo-bericht zelf de tekencodering die door de verzender is gehanteerd (er vindt geen conversie plaats). Kennen een correcte transformatie van enkele kerngegevens, die enkel worden afgeleid uit de GGS-envelop. Het transformatieschema is:
Bericht
GGS-element
WMO301 WMO301 WMO301 WMO301
Di01.stuurgegevens.functie Di01.stuurgegevens.zender.organisatie Di01.stuurgegevens.ontvanger.organisatie Di01.stuurgegevens.referentienummer
WMO304 WMO304 WMO304 WMO304 WMO304
Di01.stuurgegevens.functie Di01.stuurgegevens.zender.organisatie Di01.stuurgegevens.ontvanger.organisatie Di01.stuurgegevens.referentienummer Di01.stuurgegevens.crossRefnummer
Veld5 (onderdeel van pad of bestandsnaam) <MAPNAAM> (eventuele versie wordt verwijderd)
<WMO AANBIEDER> <MAPNAAM> (eventuele versie wordt verwijderd) <WMO AANBIEDER>
Berichten van VECOZO aan RINIS
Beschikken over metadata om (de verplichte delen van) de GGS-envelop te kunnen vullen. Het gaat daarbij om de elementen Du01.stuurgegevens functie, Du01.stuurgegevens.zender.organisatie, Du01.stuurgegevens.ontvanger.organisatie, Du01.stuurgegevens.referentienummer en (alleen voor WMO302) Du01.stuurgegevens.crossRefnummer. Hebben betrekking op een type iWmo-bericht waarvoor een ketenoperatie bestaat (bijv. Toewijzing en Declaratie). Zijn afkomstig van een AGB-code waarvoor een aansluiting op het VSP bestaat; m.a.w.: retourberichten kunnen worden afgeleverd. Zijn verzonden door een partij die de in het iWmo-bericht vermelde AGB-code mag gebruiken (heeft opgegeven in het aansluitproces bij VECOZO). Kennen een tekencodering volgens UTF-8 voor het iWmo-bericht zelf.
Berichten van RINIS aan IB
Voldoen aan de GGS-standaard. RINIS past de volgende transformatie toe op metadata:
Bericht WMO302 WMO302 WMO302
5
GGS-element Du01.stuurgegevens.functie Du01.stuurgegevens.zender.organisatie Du01.stuurgegevens.ontvanger.organisatie
Veld (onderdeel van pad of bestandsnaam) <MAPNAAM> (zonder versie-aanduiding) <WMO AANBIEDER>
De veldnamen verwijzen naar velden uit het iWmo-bericht.
5
WMO302 WMO302 WMO303 WMO303 WMO303 WMO303
Du01.stuurgegevens.referentienummer Du01.stuurgegevens.crossRefnummer Du01.stuurgegevens.functie Du01.stuurgegevens.zender.organisatie Du01.stuurgegevens.ontvanger.organisatie Du01.stuurgegevens.referentienummer
<MAPNAAM> (zonder versie-aanduiding) <WMO AANBIEDER>
Voor alle interacties
De maximale grootte van een enkel bericht (bestand danwel inhoud van een SOAP-envelop bij de webservice) is 10 MB. Knooppunten zijn niet verplicht hierop te controleren, maar er wordt ook geen aflevergarantie geboden op berichten boven 10 MB. Wanneer zich een probleem voordoet met te grote berichten, is het knooppunt dat het bericht heeft geaccepteerd van de eindafnemer verantwoordelijk voor de foutafhandeling.
Standaarden en operationele afspraken voor transport
Ontvangen berichten worden (vrijwel) direct verwerkt en indien correct, aangeboden aan het volgende knooppunt of de eindafnemer. Berichten worden afzonderlijk aangeboden en verwerkt door de knooppunten. Er wordt geen gebruik gemaakt van packaging of ZIP-files. VECOZO en RINIS gebruiken FTP voor het uitwisselen van berichten. RINIS host een FTPserver en zet berichten voor VECOZO klaar in de relevante mappen. VECOZO monitort deze map voortdurend op .DAT-bestanden (in het geval van WMO304-bericht .TXT-bestanden). Als een bestand wordt gevonden, wordt deze gedownload en daarna verwijderd. Wanneer VECOZO een bestand voor RINIS heeft, plaatst VECOZO deze in de relevante map op de FTPserver van RINIS. RINIS monitort deze mappen voortdurend op .DAT-bestanden, pakt een nieuwe bestand op voor verdere verwerking en verwijdert vervolgens het bestand op de FTPserver. Elk iWmo-bericht heeft de vorm van een bestand. De inhoud van het bestand is gelijk aan het EI-bericht. Metadata wordt in de bestandsnaam en de mappenstructuur meegegeven6. Om te voorkomen dat een bestand al kan worden verwerkt voordat het in zijn geheel op de FTP-server is geplaatst, wordt een bestand na succesvol uploaden pas voorzien van de extensie .DAT danwel .TXT. RINIS en IB gebruiken onderling web services, waarbij het verkeer plaatsvindt over RINISnet. Wanneer aflevering naar een naburig knooppunt niet lukt, wordt met een retrymechanisme gedurende ten minste een uur geprobeerd het bericht alsnog af te leveren. De knooppunten monitoren of een bericht is geaccepteerd door het naburige knooppunt, via een positieve respons op een FTP-upload (als een bericht van VECOZO naar RINIS gaat), de constatering dat een bericht is verwijderd op de FTP-server (als een bericht door VECOZO is opgehaald bij RINIS) of een positieve respons op een webservice-request (IB-RINIS v.v.).
Foutsituaties waarin de standaarden niet voorzien Daar waar technische standaarden niet voorzien in foutafhandeling, zoeken de knooppunten actief contact met elkaar. De knooppunten zijn verantwoordelijk voor de terugmelding aan de eigen achterban (VECOZO voor aanbieders, IB voor gemeenten). Voor veel voorkomende situaties kunnen 6
Een beschrijving van de mappenstructuur is bijgevoegd.
6
geautomatiseerde notificaties (bijvoorbeeld met e-mail) worden afgesproken. Over de afhandeling van de foutsituaties worden nadere afspraken gemaakt. Voorziene situaties die door de knooppunten geconstateerd kunnen worden zijn: VECOZO constateert een fout in een WMO301-bericht, maar is door ontbrekende of foutieve informatie in het bericht niet in staat een retourbericht te genereren. Een Wmo-aanbieder adresseert een bericht met een gemeentecode, maar de daarbij behorende gemeente is niet (voor het iWmo-berichtenverkeer) aangesloten op het GGK. Een gemeente adresseert een bericht met een AGB-code, maar de daarbij behorende aanbieder is niet (voor het iWmo-berichtenverkeer) aangesloten op het VSP. Ondanks het herhaaldelijk aanbieden van een bericht, lukt het niet dit af te leveren bij het naburige knooppunt door een probleem in de connectiviteit of de acceptatie van het ontvangende knooppunt. Suggestie voor beheersafspraak: als een bericht na een uur nog niet is afgeleverd, zoeken de knooppunten actief contact met elkaar. RINIS constateert een fout (niet voldaan aan schema) in een van IB ontvangen GGS-envelop. IB constateert een fout (niet voldaan aan schema) in een van RINIS ontvangen GGS-envelop. VECOZO constateert een fout in de metadatering van bestanden op de FTP-server door RINIS. (Voorbeelden van mogelijke oorzaaken De metadata van de GGS-envelop komt niet overeen met de inhoud van het iWmo-bericht, of de bestandsnaam bevat illegale karakters.) RINIS constateert op haar FTP-server een fout in de metadatering door VECOZO (niet voldaan aan afspraken RINIS-VECOZO). Een bericht overschrijdt de maximale berichtgrootte en kan niet succesvol worden afgeleverd.
Bijlagen
Specificatie STuF-“enveloppe” Gemeentelijk gegevensknooppunt, versie 1.0 Memo Uitwisseling WMO-berichten tussen VECOZO en RINIS, versie 1.0 Voorstel Definitief 5, 26 september 2014
7
