VERA 3.0. Bijlage D.4 - Keuzen verstuffing. Versie: 3.0 Datum: Status: Definitief

Transcriptie

1 VERA 3.0 Bijlage D.4 - Keuzen verstuffing Versie: 3.0 Datum: Status: Definitief Stichting VERA Veenendaal

2 Inhoud 1 Inleiding Functionele keuzes VERAStUF uitwerking Toepassen van ontwerpregels door script Ontwerpkeuzen best practices Entiteiten vraagantwoord en mutatie Voorbeeld WSDL s Afwijkingen t.o.v. StUF Afwijking VERA logisch gegevensmodel Bronsysteem Inheritance Foutafhandeling Nog niet geïmplementeerde best practices Van logisch model naar technisch berichtenformaat Versiebeheer Versie Datum Toelichting Creatie Nieuw: hoofdstuk 6 Aangepast: hoofdstuk 8 Bijlage D.4 - Keuzen verstuffing 2

3 1 Inleiding Het document stuf_best_practices.pdf dat behoort bij de documentatie van StUF is gebruikt om ontwerpregels vast te stellen voor VERA. Deze ontwerpregels zijn verwerkt in een script en op basis van die regels worden in dit script attributen vertaald en diverse bestanden aangemaakt. In dit document wordt een samenvatting gegeven van de toepassing van de best practices uit StUF binnen VERA. Conform de documentatie van StUF heeft dit document met de toepassing van StUF de term verstuffing in de titel. Dit document beschrijft de keuzen die gemaakt zijn om te komen tot de huidige VERA StUF versie zoals deze beschikbaar is gesteld. Om deze reden is het document minder relevant voor corporaties of leveranciers die de StUF willen toepassen. Het is voornamelijk bedoeld voor VERA werkgroep leden die de StUF willen uitbreiden. Het document is ook relevant voor revieuwers die het StUF spoor reviewen. Voor de reviews is het van belang om de keuzen te kennen om zodoende de discussiepunten en besluiten die genomen zijn in de werkgroep te doorgronden. De uitwerking van de WSDL s en XSD s is te vinden in bijlage D.3. Bijlage D.4 - Keuzen verstuffing 3

4 2 Functionele keuzes VERAStUF uitwerking 1. VERA gebruikt dezelfde interactiepatronen als StUF. 2. In VERA zal nog geen gebruikt gemaakt worden van samengestelde berichten. 3. De in StUF gestandaardiseerde berichtcode zal worden gehanteerd (zie stuf0301.pdf patch 15). 4. De berichtcode bepaalt de naam van het bericht / operatie en bestaat uit <mnemonic>+<berichttype>. 5. Niet alle berichttypen uit StUF worden ondersteund in VERA. De onderstaande services zullen in de WSDL van VERA mogelijk zijn: - OntvangAsynchroon Deze service dient alle ondersteunde asynchrone berichten te kunnen ontvangen. - BeantwoordVraag Deze service dient alle ondersteunde synchrone vraagberichten te kunnen verwerken. - VerwerkSynchroneKennisgeving Deze service dient alle ondersteunde synchrone kennisgevingberichten te kunnen verwerken. - VerwerkTriggerbericht Deze service dient het triggerbericht te kunnen verwerken, indien dit wordt ondersteund. De standaard foutafhandeling is overgenomen uit StUF (zie stuf03.01.pdf patch 15). VERA legt geen additionele foutafhandeling op. Bijlage D.4 - Keuzen verstuffing 4

5 3 Toepassen van ontwerpregels door script Binnen StUF wordt een mappen structuur aangemaakt. Vera volgt dit, alle bestanden worden dan ook in een map (met submappen) geplaatst. Deze map volgt de versienummering en heeft als naam Vera0310. In deze map staat een beschrijving van de entiteiten en de twee veel voorkomende interactiepatronen in de volgende structuur: - Entiteiten - vraagantwoord - Mutatie (Kennisgeving). Bijlage D.4 - Keuzen verstuffing 5

6 4 Ontwerpkeuzen best practices StUF schrijft een aantal best practices voor. De keuze voor toepassing van deze best practices en de manier van toepassing zijn in dit hoofdstuk opgenomen. 4.1 Entiteiten Bij de omzetting van de VERA klasse attributen naar een XML-schema definitie complextype s (een XML element dat andere elementen en/of attributen bevat) worden de best practices van StUF toegepast. Volgens de ontwerpregels worden in de map entiteiten de in paragraaf benoemde entiteitbestanden aangemaakt: vera0310_ent_basis.xsd De basis- en kerngegevens voor de Vera domeinen worden in dit bestand opgenomen (zie stuf_best_practices.pdf, paragraaf 2.2.1). Basis Voor iedere klasse uit het VERA gegevensmodel wordt een complextype aangemaakt in de vorm van <Mnemonic>-basis. Bijvoorbeeld voor de Betaalgegevens van een Relatie: <complextype name="relbet-basis"> <annotation> <documentation>betaalgegeven</documentation> </annotation> <sequence minoccurs="0"> <element name="identificatie" type="stuf:sleutel-e" nillable="true" minoccurs="0"/> <element name="bronsysteem" type="vera:algbro-basis" nillable="true" minoccurs="0"/> <element name="businesskey" type="vera:betaalgegevenbusinesskey-e" nillable="true" minoccurs="0"/> <element name="code" type="vera:betaalgegevencode-e" nillable="true" minoccurs="0"/> <element name="auditinfo" type="vera:algaud-basis" nillable="true" minoccurs="0"/> <element name="rekeningnummer" type="vera:betaalgegevenrekeningnummer-e" nillable="true" minoccurs="0"/> <element name="rekeninghouder" type="vera:betaalgegevenrekeninghouder-e" nillable="true" minoccurs="0"/> <element name="rekeningplaats" type="vera:vaswoo-kerngegevens" nillable="true" minoccurs="0" maxoccurs="1" /> <element name="relatie" type="vera:relrel-kerngegevens" nillable="true" minoccurs="0" maxoccurs="1" /> <element name="begindatum" type="vera:betaalgegevenbegindatum-e" nillable="true" minoccurs="0"/> <element name="einddatum" type="vera:betaalgegeveneinddatum-e" nillable="true" minoccurs="0"/> <element name="iban" type="vera:betaalgegeveniban-e" nillable="true" minoccurs="0"/> <element name="bic" type="vera:betaalgegevenbic-e" nillable="true" minoccurs="0"/> <element name="primair" type="vera:betaalgegevenprimair-e" nillable="true" minoccurs="0"/> <element name="incassowijze" type="vera:algref-basis" nillable="true" minoccurs="0"/> <element name="soort" type="vera:algref-basis" nillable="true" minoccurs="0"/> </sequence> <attribute ref="stuf:entiteittype" fixed="relbet"/> <attributegroup ref="stuf:entiteit"/> </complextype> Alle XML schema definities van alle VERA domeinen met de gegevens en attributen staan in 1 bestand. Kerngegeven De StUF-standaard kent voor de identificatie van objecten in berichten het begrip kerngegevens. De kerngegevens zijn de gegevens waarmee een object in verreweg de meeste gevallen uniek geïdentificeerd kan worden, zelfs als niet alle kerngegevens beschikbaar zijn. Voor bijvoorbeeld de Betaalgegevens van een Relatie is het rekeningnummer een identificerende sleutel: <complextype name="relbet-kerngegevens"> <complexcontent> <restriction base="vera:relbet-basis"> Bijlage D.4 - Keuzen verstuffing 6

7 <sequence minoccurs="0"> <element name="identificatie" type="stuf:sleutel-e" nillable="true" minoccurs="0"/> <element name="rekeningnummer" type="vera:betaalgegevenrekeningnummer-e" nillable="true" minoccurs="0"/> <element name="iban" type="vera:betaalgegeveniban-e" nillable="true" minoccurs="0"/> </sequence> <attribute ref="stuf:entiteittype" use="required" fixed="relbet"/> <attribute ref="stuf:novalue" use="prohibited"/> <attribute ref="stuf:scope" use="prohibited"/> </restriction> </complexcontent> </complextype> Voor de VERA gegevens klasse zijn, naast het attribuut identificatie geen logische sleutels bekend. Daarom zijn alleen de meest voor de hand liggende attributen gekenmerkt als kerngegeven. Zoals rekeningnummer en iban bij betaalgegeven. Bij natuurlijk persoon is dit bijvoorbeeld het Burger Service Nummer (BSN). vera0310_simpletypes.xsd De voor een sectormodel te gedefinieerde simpletypes en -e complextypes worden in dit aparte schema opgenomen. De simpletypes worden als volgt samengesteld: - Naam: <entiteitnaam>-<attribuutnaam> - Base type van simpletype komt overeen met de waarde uit de kolom StUF zoals gedefinieerd in de Excel sheet. Volgens een best practice wordt naast de simpletypes ook complextypes toegevoegd als extension op de simpletype. Deze worden als volgt samengesteld: - Extensie op simpletype <entiteitnaam><attribuutnaam> - Naam: <entiteitnaam><attribuutnaam>-e - StUF toevoeging: StUF:element zodat eenduidig bepaald kan worden of een element gevuld is. vera0310_stuf_simpletypes.xsd Dit bestand bevat een verwijzing naar de StUF0301.xsd, de StUF basis. En een verwijzing naar Vera03010_stuf_simpleTypes.xsd. Verdere restricties kunnen in dit bestand worden opgenomen. 4.2 vraagantwoord en mutatie De entiteiten die binnen de functionaliteit voor mutaties (Kennisgeving) en voor vraag/antwoord worden gebruikt, worden gedefinieerd als restrictions op de entiteiten in het VERA_ent_basisschema. Dit gebeurt in de twee schema's met als namen VERA_ent_mutatie.xsd en VERA_ent_vraagAntwoord.xsd. Dit resulteert in de volgende bestanden: Binnen het interactiepatroon vraagantwoord wordt een drietal bestanden gegenereerd: - vera0310_msg_vraagantwoord.xsd - vera0310_msg_stuf_vraagantwoord.xsd - vera0310_ent_vraagantwoord.xsd Binnen het interactiepatroon mutatie wordt een drietal bestanden gegenereerd: - vera0310_msg_stuf_mutatie.xsd Bijlage D.4 - Keuzen verstuffing 7

8 - vera0310_msg_mutatie.xsd - vera0310_ent_mutatie.xsd De samenstelling van de berichten VERA_msg_... en VERA_msg_stuf zijn verder beschreven in de StUF best practices (zie stuf_best_practices.pdf, paragraaf en 3.2). 4.3 Voorbeeld WSDL s In een sectormodel dienen volgens de best practices (zie stuf_best_practices.pdf, paragraaf 3.4) een aantal voorbeeld WSDL s te worden geleverd. Waar een dergelijke WSDL aan moet voldoen is in StUF.bindingen pdf opgenomen. De volgende voorbeeld WSDL s voor VERA zijn opgenomen: - vera0310_verwerksynchronekennisgeving_mutatie.wsdl - vera0310_ontvangasynchroon_mutatie.wsdl - vera0310_ontvangasynchroon_vraagantwoord.wsdl - vera0310_beantwoordvraag_vraagantwoord.wsdl. Bijlage D.4 - Keuzen verstuffing 8

9 5 Afwijkingen t.o.v. StUF Er zijn een aantal zaken waarvoor een besluit is genomen waardoor een afwijking ontstaat t.o.v. StUF. Het gaat om de volgende onderdelen: - Terminologie mapping VERA StUF VERA kent een andere terminologie dan StUF als het om entiteiten gaat. Hieronder een mapping van de termen. StUF Fundamentele entiteiten Tabelentiteiten Superentiteiten VERA Object Referentiedata Object (inheritance b.v. relatie) - Elk bericht bevat StUF stuurgegevens o Zender, ontvanger, referentienummer, CrossREfnummer, Tijdstipbericht o Aanvullend: <.> VERA organisatienummer - VERA maakt gebruik van standaard XSD DateTime type o Geldt voor VERA Time, Date en DateTime typen Bijlage D.4 - Keuzen verstuffing 9

10 6 Afwijking VERA logisch gegevensmodel De VERA bevat een logisch gegevensmodel waar in klassen en attributen zijn beschreven. De StUF hanteert een standaard werkwijze die in sommige gevallen conflicterend is met de attributen die in de logische gegevensmodellen zijn gedefinieerd. Dit hoofdstuk beschrijft de conflicten, en beschrijft welke attributen leidend zijn. 6.1 Bronsysteem Het VERA gegevensmodel beschrijft dat elke entiteit een attribuut genaamd bronsysteem bevat. De StUF hanteert een eigen systematiek om bronsystemen aan te duiden. Het aangeven van een bronsysteem van een gegeven wordt aangeduid door het StUF: systeem complex type in te vullen. Dit complex type geeft de zendende en ontvangende partij een mogelijkheid om de organisatie, applicatie, en gebruiker op te geven. Het systeem complex type is terug te vinden als zender en ontvanger binnen de stuurgegevens complex type dat ingevuld kan worden bij kennisgeving en vraagberichten. Het attribuut bronsysteem wordt vanaf VERA 3.0 als depricated beschouwd. Dat wil zeggen dat het niet wenselijk is om het attribuut bronsysteem te gebruiken bij een VERA 3.0 implementatie omdat het attribuut bij een volgende VERA StUF versie waarschijnlijk niet meer beschikbaar is. De VERA StUF werkgroep zal het attribuut in een volgende VERA StUF implementatie niet meer beschikbaar stellen in de StUF implementatie. 6.2 Inheritance Het logische gegevensmodel legt inheritance relaties tussen klassen. Het horizontale StUF model ondersteund deze relaties niet. Er is een vertaling gemaakt van deze relaties naar een platte structuur. Deze vertaling is als volgt doorgevoerd: 1. Een superklasse wordt weergegeven als een normale klasse. 2. Een afgeleide klasse bevat de attributen die zijn gespecificeerd in een basisklasse. 3. Superklassen bevatten een attribuut genaamd: soort. De onderstaande tekst beschrijft een voorbeeld van deze regel: Een klasse Relatie bevat de attributen: Naam, Adres en Soort. Een afgeleide klasse van de superklasse Relatie, genaamd Natuurlijkpersoon bevat de volgende attributen: Voornaam en Achternaam. Deze situatie is als volgt vertaald in het horizontale sectormodel: Relatie: - Naam - Adres - Soort Natuurlijk persoon: - Naam - Adres - Soort - Voornaam - Achternaam Bijlage D.4 - Keuzen verstuffing 10

11 Aan de superklassen is een attribuut toegevoegd genaamd Soort. Dit attribuut is gekenmerkt als kerngegeven. Het logische gegevensmodel kent diverse verwijzingen naar superklassen. Om onderscheid te maken tussen een super klasse of een afgeleide klasse, is er voor gekozen om het attribuut soort op te nemen als een kerngegeven zodat de afgeleide klasse bepaald kan worden op basis van het attribuut soort.

12 7 Foutafhandeling Foutafhandeling wordt gerealiseerd door gebruik te maken van de foutcodes en structuren die onderdeel uitmaken van de StUF standaard. De StUF standaard stelt dat er van synchrone en asynchrone vrije berichten, foutmeldingen beschreven dienen te worden. Deze berichten zijn niet uitgewerkt. Bijlage D.4 - Keuzen verstuffing 12

13 8 Nog niet geïmplementeerde best practices Bij de uitwerking van VERA is de scope beperkt gehouden. Er zijn daarom keuzes gemaakt in welke regels over genomen worden uit de STUF best practices en welke (nog) niet. De volgende regels zijn niet overgenomen: - Bevragen van de materiële historie. - Samengestelde kennisgevingsberichten. - Geen onderscheid in verschillende entiteittypen. - Gegevensgroepen. - Sortering. Het veld is wel opgenomen, maar de sortering is niet uitgewerkt in het horizontale sectormodel. De vragende partij is zelf verantwoordelijk voor de sortering. - Uitwerking foutcodes voor zowel synchrone als asynchrone vrijeberichten. - Synchronisatieberichten. Het advies is om de bovenstaande punten op te pakken zodra er een RFC wordt ingediend die aangeeft dat het wenselijk is om de VERA standaard uit te breiden met een van de bovenstaande punten. Bijlage D.4 - Keuzen verstuffing 13

14 9 Van logisch model naar technisch berichtenformaat Vanaf versie VERA 1.0 bestaat de documentatie van het logisch model zowel uit documenten (pdf) als MS Excel sheets (voor intern gebruik) met de entiteiten en bijbehorende attributen. Bij de uitwerking van VERA is naar een eenvoudige manier gezocht (zonder aanschaf van dure tools) om vanuit de MS Excel sheets naar een technische uitwerking te komen (XSD en WSDL). De VERA werkgroep (2) heeft het uitgangspunt gehad om de modellen te genereren zonder veel handwerk en zo generiek mogelijk vanwege mogelijke uitbreidingen aan logische entiteiten. Dit heeft geresulteerd in een script dat toegevoegd is aan de MS Excel sheets dat zorgt voor de generatie van de XSD s en de WSDL s. Om te kunnen genereren is er informatie toegevoegd, zoals een indicatie of iets een kern(sleutel)gegeven is en hoe de associatie (relationship) er uit ziet. De uitbreiding is de nieuwe standaard voor de uitwerking van de VERA domeinen. Een partij die een WSDL implementeert kan naar alle waarschijnlijkheid niet alle operaties implementeren en aanbieden. De VERA WSDL is dan ook meer een template. De ontvangende partij verwijderd de operaties uit de WSDL die niet zijn geïmplementeerd. Deze manier van werken Impliceert het volgende: Aan de WSDL is af te leiden of synchrone of asynchrone berichten worden ondersteund. Bij het implementatietraject dienen WSDL s uitgewisseld te worden om zo te bepalen wat er wordt ondersteund. Zie het Scenario: bevragen van natuurlijk persoon in bijlage D.1 voor een voorbeeld implementatie scenario. Bijlage D.4 - Keuzen verstuffing 14