Handleiding Testvoorziening istandaarden (TiS) 4 mei 2017

Transcriptie

1 Handleiding Testvoorziening istandaarden (TiS) 4 mei 2017

2 Inhoud 1 Toegang tot de Testvoorziening istandaarden (TiS) istandaarden-account Bedoeling en ontwikkeling WSDL Endpoint 5 2 Gebruik en werking Testvoorziening istandaarden (TiS) De rol van TiS Werking: volledige doorloop van processen TiS als gemeente: Wmo en Jeugdwet <TestCase> Vulbericht Interactie en volgorde TiS als zorgaanbieder <TestCase> Interactie en volgorde Controles Alle validaties binnen het bericht Berichtoverstijgende controles 9 3 SOAP-envelop WSDL-bestand met voorbeeld-requests downloaden WS-security header istandaarden-header 10 4 Bericht aanbieden:<offerfile*> SOAP-request <OfferFileRequest> SOAP-response <OfferFileResponse> Naamgeving gegenereerd bestand SOAP Fault: foutmeldingen 13 5 Bericht ophalen: <RequestFile*> SOAP request: <RequestFileRequest> RequestFileResponse 15 Handleiding Testvoorziening istandaarden (TiS) 2/16

3 Inleiding De Testvoorziening istandaarden (TiS) is een webservice van Zorginstituut Nederland voor leveranciers van iwmo- en ijw-software. De softwareleveranciers kunnen hun producten testen in de rol van elke partij die deelneemt aan het istandaarden-berichtenverkeer, en zo nodig verbeteren. TiS ondersteunt softwareleveranciers bij de bouw van hun softwareproducten, waarmee hun klanten gemeenten, zorgaanbieders snel en soepel digitale Wmo- en Jw-berichten kunnen uitwisselen via istandaarden. TiS biedt een online-simulatieomgeving waar softwareleveranciers hun producten kunnen testen in de rol van elke partij die deelneemt aan het istandaarden-berichtenverkeer. TiS werkt met een geautomatiseerd testproces volgens vastgestelde en ingebouwde scenario s. Daarmee worden verzendende en ontvangende partijen gesimuleerd. Vooralsnog werkt TiS alleen met iwmo 2.1 en ijw 2.1. Voor die istandaarden kan de softwareleverancier in TiS een testscenario kiezen, en testberichten versturen. TiS reageert als de ontvangende partij met een retour- en vervolgbericht. Voor en ook door softwareleveranciers TiS is ontwikkeld samen met softwareleveranciers die actief zijn in het Wmoen Jw-domein. De service wordt voortdurend voorzien van nieuwe testscenario s. Zo wordt TiS een volwaardig product dat softwareleveranciers structureel ondersteunt bij de bouw van hun software. Meer informatie Hebt u vragen of opmerkingen over de Handleiding Testvoorziening istandaarden? Neemt u dan contact op met: Zorginstituut Nederland Beheerteam istandaarden (020) info@istandaarden.nl Bezoekadres Eekholt XH Diemen Postadres Postbus AH Diemen Handleiding Testvoorziening istandaarden (TiS) 3/16

4 Versiebeheer Versie Datum Toelichting en status mei 2017 Definitief Handleiding Testvoorziening istandaarden (TiS) 4/16

5 1 Toegang tot de Testvoorziening istandaarden (TiS) In dit hoofdstuk leest u wat u nodig hebt om toegang te krijgen tot TiS, wat de bedoeling is van de testvoorziening en waar u de WSDL en het endpoint vindt. 1.1 istandaarden-account Om gebruik te kunnen maken van TiS hebt u een geldig istandaarden-account nodig met de juiste gebruikersrechten. Via de module Accountbeheer kunt u een istandaarden-account aanvragen en beheren. Hebt u nog geen account, is het inactief of hebt u nog niet de juiste rechten? Neemt u dan contact op met de Servicedesk istandaarden, op werkdagen bereikbaar van 7.30 tot uur via (020) of info@istandaarden.nl. 1.2 Bedoeling en ontwikkeling TiS is bedoeld voor de ondersteuning bij de implementatie van de nieuwe releases van de istandaarden. Op dit moment kunnen testscenario s worden doorlopen voor de iwmo 2.1 en ijw 2.1. Voor nieuwe releases binnen de istandaarden wordt de testvoorziening ook beschikbaar gesteld. In aanloop naar nieuwe releases volgen nieuwe publicaties. U biedt testberichten aan, waarop de testvoorziening een functionele reactie geeft overeenkomstig het bedrijfsproces. 1.3 WSDL Om TiS te kunnen gebruiken, hebt u de WSDL (Web Service Description Language) nodig. U kunt de WSDL als.zip-bestand downloaden op de TiSpagina op Endpoint Om de webservice te benaderen, hebt u dit endpoint nodig: Handleiding Testvoorziening istandaarden (TiS) 5/16

6 2 Gebruik en werking Testvoorziening istandaarden (TiS) In dit hoofdstuk leest u meer over de werking en het gebruik van de testvoorziening. 2.1 De rol van TiS De testvoorziening speelt de rol van tegenpartij. Afhankelijk van het domein, op dit moment nog enkel de Wmo of Jeugdwet, speelt de testvoorziening dan de rol van zorgaanbieder, gemeente of zorgkantoor. Wilt u software testen voor de zorgaanbieder, dan speelt TiS de rol van gemeente. En wilt u software testen voor een gemeente, dan simuleert TiS de rol van zorgaanbieder 2.2 Werking: volledige doorloop van processen TiS versie 1.0 gaat altijd uit van een volledige doorloop van de processen die in het echte berichtenverkeer ook plaatsvinden tussen partijen in het werkveld van iwmo en ijw 2.1. In TiS is daarom de volgorde van de berichten altijd hetzelfde tussen start en einde. De rol die de testvoorziening moet spelen, bepaalt wat de volgorde van de berichten moet zijn. Het is met TiS 1.0 nog niet mogelijk een afwijkende berichtvolgorde te doorlopen, bijvoorbeeld een scenario om na een toewijzing [301] direct een factuur [303] te sturen en de start van zorg [305] over te slaan. Een aangeboden bericht kan per bericht één cliënt en/of één product bevatten. Alle berichten die TiS aanmaakt binnen een testsessie krijgt u terug in de response. Een response bevat dus alle berichten die TiS terugstuurt van een sessie. 2.3 TiS als gemeente: Wmo en Jeugdwet In dit scenario is TiS de gemeente en is de initiator de zorgaanbieder. Het scenario begint met een vulbericht. De informatie in het vulbericht dient als input voor berichten die TiS aanmaakt en om berichtoverstijgende validaties uit te voeren wanneer informatie niet in eerder aangeboden berichten zit <TestCase> Bij het scenario TiS als gemeente zijn deze testcases mogelijk: <TestCase> 1 Wmo_TiS_Als_Gemeente- ZA_Als_Initiator 2 JW_TiS_Als_Gemeente- ZA_Als_Initiator Toelichting Berichten gaan over de Wmo. De berichten die ingestuurd moeten worden, zijn vanuit de rol als zorgaanbieder. TiS acteert als gemeente. Berichten gaan over de Jeugdwet. De berichten die ingestuurd moeten worden, zijn vanuit de rol van zorgaanbieder. TiS acteert als gemeente. Hoe deze waarden ingezet moeten worden, staat beschreven in hoofdstuk 4. Handleiding Testvoorziening istandaarden (TiS) 6/16

7 2.3.2 Vulbericht Om het testscenario goed te kunnen uitvoeren, moet vooraf een aantal gegevens bekend zijn om gewenste controles uit te voeren en berichten aan te maken. Het vulbericht is gebaseerd op het 301-bericht en moet geldig zijn volgens de schemadefinitie van de 301: WMO301 voor een Wmo-scenario en JW301 voor een Jeugdwet-scenario. In het commentaarveld van de cliënt kan vervolgens het tarief worden opgenomen. Het mogen alleen cijfers zijn, een tarief van 12,45 vult u bijvoorbeeld als [xpath: /Bericht/Clienten/Client/Commentaar] Interactie en volgorde De afbeelding en de tabel tonen de interactie tussen en de volgorde van berichten wanneer TiS als gemeente acteert. Tussen Wmo en Jeugdwet bestaan daarbij geen verschillen. Vanaf ontvangst van de toewijzing acteert TiS als initiator. State Bericht initiator (zorgaanbieder) Actie TiS (gemeente) en nieuwe State 1 emptystate - Vulbericht - Geen - Er komt hier in de soap-response wel een Id terug. Dit Id moet overgenomen worden in de vervolg requests om de berichten aan elkaar te kunnen koppelen - (Status = startstate) 2 startstate (verzoek om toewijzing) 3 x315state (retour toewijzing) (retour verzoek om toewijzing) (toewijzing) - (State = x315state) - Geen - (State = x302state) Handleiding Testvoorziening istandaarden (TiS) 7/16

8 4 x302state (start zorg) (retour start zorg) - (State = x305state) 5 x305state (declaratie/fac tuur) (retour declaratie/factuur) - (State = x303state) 6 x303state (stop zorg) (retour stop zorg) 2.4 TiS als zorgaanbieder In dit scenario is TiS de zorgaanbieder en is de initiator de gemeente. De berichtstappen starten vanuit de zorgaanbieder, hierdoor reageert TiS met heenberichten op retourberichten die niet bij elkaar horen. Bijvoorbeeld: TiS reageert met een factuur (303) wanneer een retourbericht is ontvangen van het start zorg-bericht (306). Ook in de rol van TiS als zorgaanbieder begint een nieuw scenario met een vulbericht dat gebaseerd is op het toewijzingsbericht (301). Zie paragraaf <TestCase> Bij het scenario TiS als zorgaanbieder zijn deze testcases mogelijk: <TestCase> 1 Wmo_TiS_Als_ZA_en_I nitiator 2 JW_TiS_Als_ZA_en_Ini tiator Toelichting Berichten gaan over de Wmo. De berichten die ingestuurd moeten worden, zijn vanuit de rol van gemeente. TiS acteert als zorgaanbieder. Berichten gaan over de Jeugdwet. De berichten die ingestuurd moeten worden, zijn vanuit de rol van gemeente. TiS acteert als zorgaanbieder. Hoe deze waarden ingezet moeten worden, staat beschreven in hoofdstuk Interactie en volgorde De afbeelding en de tabel tonen de interactie tussen en de volgorde van berichten wanneer TiS als gemeente acteert. Tussen Wmo en Jeugdwet bestaan daarbij geen verschillen. Vanaf ontvangst van de toewijzing acteert TiS als initiator. Handleiding Testvoorziening istandaarden (TiS) 8/16

9 State Bericht initiator (gemeente) Bericht TiS (zorgaanbieder) 1 emptystate - Vulbericht (verzoek om toewijzing) - (State = startstate) 2 startstate (retour verzoek om toewijzing) - Geen - (State = x316state) 3 x316state (toewijzing) (retour toewijzing) (melding aanvang zorg) - (State = x301state) 4 x301state (retour melding aanvang zorg) 5 x306state (retour factuur/declaratie) 6 x304state (retour melding einde zorg) (factuur/declaratie) - (State = x306state) (melding einde zorg) - (State = x304state) - Geen - (State = x308state 2.5 Controles TiS voert altijd dezelfde controles uit zoals die in de Validatiemodule zijn geïmplementeerd. Dit zijn de validaties die binnen een bericht uitgevoerd kunnen worden. Daarnaast voert TiS een aantal berichtoverstijgende regels uit, waarbij in enkele gevallen het vulbericht als uitgangspunt dient Alle validaties binnen het bericht Bericht wordt gevalideerd op: soort en type bericht; structuur; aanwezigheid van verplichte velden; correcte vulling; technische en berichtspecifieke bedrijfsregels Berichtoverstijgende controles Aanvullend controleert TiS op de berichtoverstijgende regels. De releasenotes bij TiS, die gepubliceerd zijn op de TiS-pagina, geven de actuele status aan. Handleiding Testvoorziening istandaarden (TiS) 9/16

10 De regels die nu zijn geïmplementeerd: TR019: bij een output- of inspanningsgerichte werkwijze moet de melding van de start of de beëindiging van de ondersteuning gerelateerd zijn aan een toewijzing (op basis van de sleutelvelden). TR096: Begindatum moet overeenkomen met de actuele melding start ondersteuning die op of voor Einddatum ligt. TR300: indien de toewijzing volgt op een Verzoek om toewijzing-bericht, moet ReferentieAanbieder worden overgenomen van het betreffende Verzoek om toewijzing-bericht (315). Handleiding Testvoorziening istandaarden (TiS) 10/16

11 3 SOAP-envelop TiS maakt gebruik van het SOAP-protocol. Aanroepen naar de webservices dienen aan dit protocol te voldoen. Het WSDL-bestand dat bij TiS hoort, beschrijft hoe een juiste aanroep naar de webservice eruitziet. 3.1 WSDL-bestand met voorbeeld-requests downloaden U kunt de WSDL als.zip-bestand downloaden op de TiS-pagina op Voorbeeld-requests maken deel uit van de WSDL, ze zijn beschikbaar als apart.zip-bestand op de TiS-pagina. 3.2 WS-security header Als beveiligingsmethodiek maakt TiS gebruik van WS-security 1.0. De header van de SOAP-envelop dient een WS-security header te zijn. Een voorbeeldbericht van de WS-security header: <soapenv:header> <wsse:security xmlns:wsse=" <wsse:usernametoken> <wsse:username>gebruikersnaam</wsse:username> <wsse:password Type=" </wsse:usernametoken> </wsse:security> </soapenv:header> De WS-security header bevat deze parameters: Element Formaat/lengte Verplicht Beschrijving Username String Ja De gebruikersnaam van de istandaarden-gebruiker die de service aanroept. De gebruiker moet geautoriseerd zijn voor het gebruik van TiS. Zie hoofdstuk 1. Password String Ja Het wachtwoord van de istandaarden-gebruiker. Handleiding Testvoorziening istandaarden (TiS) 11/16

12 4 Bericht aanbieden:<offerfile*> Als u een bericht aanbiedt in TiS, beoordeelt de voorziening het bericht. Indien van toepassing reageert TiS op uw request met een nieuw bericht. 4.1 SOAP-request <OfferFileRequest> Het onderdeel OfferFileRequest is bedoeld voor het aanbieden van een bericht aan de testvoorziening. Hiervoor gelden de volgende voorwaarden. Een voorbeeld van een request: <soapenv:envelope xmlns:test= xmlns:soapenv= > <soapenv:header> <wsse:security xmlns:wsse= > <wsse:usernametoken> <wsse:username>username</wsse:username> <wsse:password Type= >password</wsse:password> </wsse:usernametoken> </wsse:security> </soapenv:header> <soapenv:body> <test:offerfilerequest> <test:id> <test:testcase>wmo_tis_als_gemeente-za_als_initiator</test:testcase> <test:id>[sessionuuid]</test:id> </test:id> <test:message> <test:xml> [istandaarden xml-bericht] </test:xml> </test:message> </test:offerfilerequest> </soapenv:body> </soapenv:envelope> De body van het request bevat deze parameters: Element Formaat Verplicht Beschrijving TestCase String Ja Beschrijving van de testcase. De waarde moet een van de volgende zijn: JW_TiS_Als_Gemeente- ZA_Als_Initiator JW_TiS_Als_ZA_en_Initiator Wmo_TiS_Als_Gemeente- ZA_Als_Initiator Wmo_TiS_Als_ZA_en_Initiator Handleiding Testvoorziening istandaarden (TiS) 12/16

13 Id String Nee De unieke sleutel voor een (test-)sessie. De eerste keer (startstate) moet dit element leeg gelaten worden, zodat TiS dit opvat als het starten van een nieuwe sessie en reageert met het terugsturen van een nieuwe Id in de SOAP-response in het element./offerfileresponse/id/id. In de vervolgrequests ofwel: bij het aanbieden van de vervolgberichten moet dit sessionuuid worden ingevuld om de berichten aan elkaar te kunnen relateren en controleren ten opzichte van elkaar. Xml String Ja Neem hier het bericht op dat ingestuurd moet worden aan TiS. 4.2 SOAP-response <OfferFileResponse> De response geeft terugkoppeling of het ingestuurde bericht behandeld kan worden en in welke state TiS komt. Wanneer een startbericht is ingestuurd, maakt de testvoorziening een Id aan en stuurt deze terug. Een voorbeeldresponse: <soapenv:envelope xmlns:test=" xmlns:soapenv=" <soapenv:body> <test:offerfileresponse> <test:id> <test:testcase> Message processed successfully. Status is 'wmo315state'.use RequestFile applying the Id(s) below to request the generated messages </test:testcase> <test:id>[sessionuuid]</test:id> </test:id> </test:offerfileresponse> </soapenv:body> </soapenv:envelope> De response bevat deze waarden: Element Formaat/lengte Verplicht Beschrijving TestCase String Ja Bevat de omschrijving in welke state TiS voor deze sessie is gezet Id String Ja Id bevat in de response de sessionuuid Naamgeving gegenereerd bestand De bestanden die TiS aanmaakt, hebben altijd een vaste structuur: <TestCase>.<sessionUUID>.<berichtsoort>.xml Bijvoorbeeld: Wmo_TiS_Als_Gemeente-ZA_Als_Initiator.abcd-1234-wb.wmo316.xml Handleiding Testvoorziening istandaarden (TiS) 13/16

14 4.3 SOAP Fault: foutmeldingen In sommige situaties ontstaan foutmeldingen, die u geretourneerd krijgt als SOAP Fault. Het gaat om: Gebruikersinformatie is onjuist gevuld. Gebruiker beschikt niet over de vereiste autorisatie. Het request is onjuist. Niet alle verplichte velden zijn gevuld. Het berichttype wordt niet ondersteund. De verwachte vulling klopt niet Meer dan 1 cliënt/adres/beschikking/toewijzing Handleiding Testvoorziening istandaarden (TiS) 14/16

15 5 Bericht ophalen: <RequestFile*> Nadat u een bericht hebt aangeboden aan TiS, reageert de testvoorziening naargelang de status met het aanmaken van bestanden. Deze zijn door de softwareleverancier met het betreffende request op te halen. NB TiS versie 1.0 geeft alle aangemaakte berichten die binnen een sessie worden aangemaakt terug. 5.1 SOAP request: <RequestFileRequest> Het onderdeel RequestFileRequest is bedoeld om de berichten die TiS aanmaakte op te halen. Welke bestanden er klaarstaan, is teruggegeven in de SOAP-response <OfferFileResponse>, zie hoofdstuk 4. Een voorbeeldbericht van het request: <soapenv:envelope xmlns:test=" xmlns:soapenv=" <soapenv:header> <wsse:security xmlns:wsse=" <wsse:usernametoken> <wsse:username>username</wsse:username> <wsse:password Type=" </wsse:usernametoken> </wsse:security> </soapenv:header> <soapenv:body> <test:requestfilerequest> <test:id> <test:testcase>wmo_tis_als_gemeente-za_als_initiator</test:testcase> <test:id>sessionuuid</test:id> </test:id> </test:requestfilerequest> </soapenv:body> </soapenv:envelope> De body van het request bevat deze parameters: Element Formaat Verplicht Beschrijving TestCase String ja Beschrijving van de testcase. De waarde moet een van de volgende zijn: JW_TiS_Als_Gemeente- ZA_Als_Initiator JW_TiS_Als_ZA_en_Initiator Wmo_TiS_Als_Gemeente- ZA_Als_Initiator Wmo_TiS_Als_ZA_en_Initiator Id String ja Vul hier de sessionuuid in van de huidige sessie. Handleiding Testvoorziening istandaarden (TiS) 15/16

16 5.2 RequestFileResponse De response geeft het opgevraagde bericht terug. Een voorbeeld: <soapenv:envelope xmlns:tns=" xmlns:soapenv=" <soapenv:body> <tns:requestfileresponse> <tns:id> <tns:testcase>wmo_tis_als_gemeente-za_als_initiator</tns:testcase> <tns:id>sessionuuid</tns:id> </tns:id> <tns:message> <tns:xml xmlns:n1=" <alle door TiS aangemaakte berichten binnen een sessie> </tns:xml> </tns:message> </tns:requestfileresponse> </soapenv:body> </soapenv:envelope> De WS-security header bevat deze parameters: Element Formaat/lengte Verplicht Beschrijving TestCase String Ja De huidige TestCase Id String Ja De huidige sessie Xml String Ja Bevat alle XML-berichten van de huidige sessie Handleiding Testvoorziening istandaarden (TiS) 16/16