MAGDA standaarden & richtlijnen April 3, 2017 MAGDA standaarden & richtlijnen Coördinatiecel Vlaams e-government (CORVE) Lieven Verreycken, SOA Consultant Architect (HB) Hans Arents, Senior Adviseur (CORVE) Web: http://www.vlaanderen.be/e-government/

Objectief van de werkgroep Informatie verstrekken voor afnemers, bronnen, leveranciers Forum voor vragen en overleg ivm toekomstige evolutie van de standaard Nuance standaard – richtlijn – best practice Standaard = MOET Richtlijn = BEST Eerste sessie: focus op informatie verstrekken Volgende sessies: af te spreken

Aanleiding Update van MAGDA documentatie xsd richtlijn 2.0 FTP richtlijnen (sftp) Migratie van url’s Vragen naar uitbreiding vanuit authentieke bronnen Nieuwe bronnen zoals Digitale Bouwaanvraag en LNE-VEA-EPB O&V Da Vinci Discimus

Agenda deze sessie Doel MAGDA Doelstelling van de MAGDA standaarden Voorstelling van de standaard In combinatie met hoe in de praktijk toegepast op MAGDA Vragen Voorstellen voor uitbreidingen

Doel van het programma MAGDA MAximale GegevensDeling tussen Administraties Éénmalig inzamelen, veelvuldig gebruiken Decretaal vastgelegd Gestandardiseerde diensten, onafhankelijk van de bron Aantonen dat SOA werkt in de praktijk Voorbeeldfunctie voor andere diensten – “advies” – richtlijnen functie Voorbeeld technieken MAGDA overgenomen door projecten met webservices Onderwijs & Vorming voor webservices voor Universiteiten en Hogescholen Openbare Werken … Nieuwe authentieke bronnen via MAGDA gateway zoals LED (Diploma)

MAGDA: basis begrippen Vereenvoudigd model en terminologie Afnemers: ook leveranciers “kapstok” voor verdere verfijning

Doelstelling standaarden Voordeel: winst in tijd en kost Eénzelfde manier van werken voor alle aansluitingen, ongeacht: ondernemings-, persoons-, … diensten MAGDA, LED, … diensten Richtlijn bij ontwerp Bij keuze -> geen onnodige discussie Starten van sjablonen en voorbeelden Re-use Nadeel: tragere evolutie in geval van wijzigende vereisten Soms leren leven met niet-optimale beslissingen uit verleden

Impact van wijziging op standaard Gebruik – dienst gemiddeld door 5,5 afnemers gebruikt Impact op alle afnemers die de diensten gebruiken

Afnemers en bronnen Afnemers: zowel federaal, regio als lokaal Diensten: business diensten naar federale bronnen die niet compliant zijn aan de VO standaarden, gateway diensten naar Vlaamse bronnen die wel al VO standaard diensten hebben, maar die niet rechtstreeks ontsloten worden voor privacy (4-ogen) vereisten. Bronnen: grote diversiteit aan bronnen

Bronnen en soorten diensten Standaard “soorten” diensten Met respectievelijke naamgeving

Functionele domeinen Voorbeeld toepassingen oa met “early adopters” italic : gepland Afnemers: verfijnen van beleidsdomeinen naar toepassingen binnen de beleidsdomeinen. Dit is geen exhaustieve lijst van de toepassingen. Diensten worden gegroepeerd in domeinen (policies per domein, security regels, groepering voor de afnemers voor terugvinden van diensten)

Standaard: functioneel domeinen Specifieke objecten per functioneel domein Ook in naamgeving dienst Fictief voorbeeld Inburger.GeefDossier BouwAanvraag.GeefDossier Voordeel Beheersbaar per functioneel domein Klassificatie en terugvinden van services

Naamgeving diensten Groot aantal diensten (niet de verschillende versies gelijst) Volgens een standaard naamgeving (operatie + object) – intussen een methode die door de meeste andere service providers in Vlaanderen is overgenomen. Italic: diensten “under construction”

Standaard: naamgeving diensten Domein.Functie(Aard)Doelobject(Bereik) Domein Deels in 1.1 diensten, overal toegepast sinds 1.2 Functie Geef, Zoek, Creeer, Registreer, Wijzig, … Doeloject Onderneming, Persoon, Inschrijving, … Aard Mutaties, Historiek Document “Naamgeving van MAGDA diensten.versie1”

Naamgeving Toegepast op / vertaald naar technische services Webservice 1 naam – 1 dienst – 1 operatie FTP Geen operatie

Naamgeving : redenen vd keuze FTP en webservices Naamgeving voor service vs operatie vs url vs context/naam? Welke operaties al dan niet te bundelen in één service? Incrementeel toevoegen van nieuwe diensten zonder impact op de bestaande webservice specificaties en versies Typische SOA aanpak Eenduidig voor toelatingen toegekend op niveau van de service

Naamgeving : redenen vd keuze Welke naamgeving niveau service vs niveau operatie vs url vs context/naam? Welke operaties al dan niet te bundelen in één service ? Entity Service: dienst Persoon, Onderneming bv? Operaties GeefPersoon, ZoekPersoonOpNaam, … Welke naam op de operatie? Welke naam op de url Welke naam in de context? Wat met geen Entity Services? Schrijf en lees diensten in afzonderlijke webservices ?

Naamgeving : redenen vd keuze Incrementeel toevoegen van nieuwe diensten zonder impact op de bestaande webservice specificaties en versies Incrementeel = eigen aan SOA = praktijk MAGDA Starten met GeefPersoon 1.0, ZoekPersoonOpNaam 1.0, … Wijzigingen op de GeefPersoon Nieuwe versie webservice? Van 1 operatie of alle operaties? Toelatingen Niveau van de webservice – operatie ?

Diensten Vlaamse bronnen VOP entiteit volgens mij alleen binnen Orafin

Geef – Publiceer Diensten Gebruik van éénzelfde object, of men nu via een Vraag-Antwoord of een Publiceer werkt

Standaard Objecten in vraag-antwoord services en publicaties zijn dezelfde Voordeel Consistentie voor de afnemer

Diensten met eenduidig begrippenkader Elke bron heeft eigen nomenclatuur. Voor de Vlaamse bronnen proberen zoveel mogelijk te standardiseren aan de bron. Voor federale bronnen standardisatie via de diensten laag. Vermijdt dat elke afnemer telkens andere begrippen moet gebruiken.

Standaard: eenduidig begrippenkader Voordeel naar documentatie Begrippenlijst per functioneel domein Duidelijke semantiek voor de afnemer Sterk afhankelijk van de authentieke bronnen Gegeven van authentieke bron mag niet gewijzigd worden (inhoud) Ondernemingsnummer: altijd 10 lang bij MAGDA, + voorloopnul Andere codes voor bv geslacht code kan verschillen van de authentieke bron Zolang deze 1 op 1 mappen met de bron, is er geen informatieverlies Eenzelfde begrip kan door authentieke bron verschillend geïmplementeerd zijn in verschillende services

Standaard Naamgeving wsdl – xsd – url Folder structuur van de specificatie Types en elementen: generiek en voor functionele domeinen Versiebeheer in de specificatie xsd modellering

Standaard xsd (voor FTP en webservice) wsdl (voor webservice) Verzoek-Repliek / Vraag-Antwoord Context – Inhoud – Uitzondering Context en Uitzonderingen identiek voor alle diensten Inhoud specifiek per dienst Dienst specifiek Inhoud Generieke domein objecten wsdl (voor webservice) url (voor webservice)

Verzoek

Sjabloon xsd Dienstnaam, namespace, schema locaties van de xsd’s aan voor xsd Alleen het VraagInhoudType dienst specifiek maken Refereren naar een domein specifiek objet

Repliek

wsdl sjabloon

wsdl sjabloon <wsdl:service name=“GeefA"> <wsdl:port name="webServiceHttpPort" binding="webServiceHttpBinding"> <soap:address location="https://magdadienst.vlaanderen.be/MagdaDienst-02.00/soap/WebService"/> </wsdl:port> </wsdl:service> <wsdl:portType name="webServicePortType"> <wsdl:operation name=“GeefA"> <wsdl:input name="GeefARequest" message="GeefARequest"/> <wsdl:output name="GeefAResponse" message="GeefAResponse"/> </wsdl:operation> </wsdl:portType> <wsdl:message name="GeefAResponse"> <wsdl:part name="Repliek" element="GeefAResponse"/> </wsdl:message>

Naamgeving elementen Message (input/output): Request - Response Top Element (input/output): Verzoek – Repliek Enige element dat globaal gedefinieerd wordt Alle andere elementen via Type definities

FTP variant FTP variant Meerdere vragen / antwoorden “Service” folder Vroeger 1000, nu onbeperkt “Service” folder

Domeinen : principe

Domeinen Generiek: voor alle berichten Basisregisters Persoon, Onderneming, … Sleutels van de basisregisters niet alle “ballast” van het volledige domein mee te nemen bij “include” vanaf 2.0 Business specifieke: include de basisregisters of andere business specifieke

Files en folders per domein Vanaf 1.2 soms, vanaf 2.0 altijd Domein.xsd: alle definities binnen deze folder DomeinComplex.xsd: alle complex types DomeinEnum.xsd: alle enumeraties DomeinSimple.xsd: alle simple types Vervangt Domein.xsd GeneriekDataTypes.xsd GeneriekDataCodes.xsd GeneriekDataKern.xsd

Domeinen: beheerders CORVE MAGDA Generiek Basisregisters Persoon, Onderneming, … Verschillende Business afdelingen ism CORVE Voor de eigen business specifieke Bijvoorbeeld LED voor Bewijs LED specifieke extensies voor de MAGDA gateways BewijsExtensie.xsd met BewijsPublicatieType

Versies Files en folders Folders voor de domeinen met versieaanduiding Bijvoorbeeld: Generiek-02.00 Voordeel: duidelijk correcte versie van het volledig domein meenemen Nadeel: alle include/import statements en namespaces versie specifiek File namen zonder versieaanduiding Namespace xmlns:generiek="http://generiek-02_00.vip.vlaanderen.be" Prefix zonder versieaanduiding Uitzondering: indien meerdere versie van 1 domein gebruikt in de service Namespace met versieaanduiding

Generiek: partijen in het bericht

Ontwerp beslissing Referte Alternatieven voor de Afzender: verplicht voor Ontvanger: onbekend bij versturen van het bericht. Alternatieven Verschillende partijen, met validatie logica in de xsd 1 PartijType, met validatie logica buiten de xsd

Validaties bij aansluiting op T&I Vooraleer “go” op productie Belangrijkste controles: Aantal representatieve testgevallen Correct gebruik van referte Vereist voor tracebility in productie Aantal optionele elementen Afzender en Ontvanger Naam: controle verdwijnt Verplicht veld Identificatie is vereist INSZ van gebruiker voor persoonsdiensten: verdwijnt ?

Richtlijnen schema – xsd modellering Taal (1) Industrie standaarden (5) Modulariteit (9) Structuur (1) Namespace (8) Versie (3) Andere (2) Document “CORVE_VIP_Richtlijnen_XML_Schema” Componenten (Elementen, Types, …) Naamgeving (13) Definitie (15) Ontwerp (11)

Algemeen Maak xsd niet te complex Te begrijpen door afnemers Aantal elementen vd sequence ComplexType: max 10 Indien meer: is men met nog 1 type bezig? Diepte van de boom: max 5 niveaus Indien meer: Verschillende objecten? Verschillende services?

Naamgeving (Element, Types, …) Nederlands (NAAM001) Vertalen van business specifieke concepten naar het Engels -> good luck Nadeel: ontsluiting naar federale en Europese afnemers Afkortingen (NAAM011) Alleen de “gekende” / “gangbare” afkortingen DmfA, KBO, percid

Enumeraties Origineel: alle enumeraties in CodeType / EnumType Voortschrijdend inzicht Enumeraties zijn volatiel Zelfs diegene waarvan men denkt dat ze stabiel zijn bv geslacht Wijziging enumeratie breekt het contract Conclusie: alleen enumeraties bij zekerheid NAAM005, NAAM006, ONTW007

Naamgeving (Element, Types, …) Upper Camel Case / Pascal Case (NAAM009) ISO 11179 (NAAM002) “Type” suffix voor types (NAAM007) <xs:complexType name=“PersoonType"> <xs:sequence> <xs:element name=“INSZ" type=“generiek:INSZType"> <xs:element name=“Geslacht" type=“GeslachtType“ minOccurs="0"> <xs:element name=“Geboorte" type=“GebeurtenisType"> <xs:element name=“Overlijden" type=“GebeurtenisType“ minOccurs="0"> </ xs:sequence> </ xs:complexType>

Collections Afzonderlijk element voor de collection Voordeel ipv unbounded rechtstreeks binnen het bovenliggende Type Voordeel Leesbaarheid Code generatie Parsing

Typering Steeds Types voor de elementen binnen ComplexType Complex of Simple Any Type: slechts uitzonderlijk toegelaten Aantal SimpleType voor strings Voordeel Leesbaarheid

Generiek Adres uit 1.2 Straat, gemeente NIS Straat code In principe verplicht Optioneel wegens uitzonderlijk niet ingevuld door bron  NIS Straat code Idem cfr supra NIS gemeente code CRAB straat code Adres Internationaal

Beschrijving - omschrijving Attribuut dat tekstuele beschrijving geeft van een ander element, meestal een code Geslacht Omschrijving Element Kan ook andere benaming zijn, bijvoorbeeld Diagnose voor Uitzondering

Types en operaties Op éénzelfde object Creatie: aantal constaints >> default Type Consultatie: mogelijk minder constraints (niet alles via Creatie service aangemaakt) >> InputType, AanmaakType Opzoeking: criteria met weinig constraints >> CriteriaType

Datums en tijd Tijdstip Type Creatie en modificatie datum van object Tijd en Datum Creatie en modificatie datum van object Periodes Begindatum en Einddatum 4 combinaties verplicht – optioneel in 2.0

Simple Types Getal: string met pattern <xs:simpleType name=“xxxType"> <xs:restriction base=“xs:string”> <xs:maxlength name=“3"> <xs:pattern value="[0-9]{1,3}"/> </xs:restriction > </ xs:simpleType>

Wijzigingen 2.0 tov 1.x Doelstellingen gateways redundante systemen voor hogere beschikbaarheid Contract van gateway en directe business dienst na gateway zijn gelijk

Wijzigingen 2.0 tov 1.x Referte Oorsprong van de fout 36 ipv 24 lang: mogelijk om een uuid te gebruiken Met 24 lang was er ook een codering met milliseconden + random, maar deze is niet noodzakelijk uniek met MAGDA load-balanced systemen voor 24:7 beschikbaarheid (minieme kans op collision). Oorsprong van de fout

Wijzigingen 2.0 tov 1.x Referte Oorsprong van de fout MAGDA of Bron: LED, … Codering van de fouten via 5 cijfers (99999) Geen unieke set van nummers over alle bronnen heen Wel herbruik van common codes MAGDA Bv geen gegevens gevonden

Standaarden protocols

Standaard formulier aansluiting vd afnemer Standard formulieren voor aanvraag Identificatie aanvrager Motivatie Machtigingen privacy gevoelige diensten Validatie in T&I omgeving Timing forecast

Richtlijnen documenten Wsdl – xsd – url Xml schema en componenten Bronnen – leveranciers – afnemers Versiebeheer: hoe lang parallelle versies ondersteunen Naamgeving van diensten FTP Ondersteuning afnemers in integratietraject: validatie bij aansluiting

Bedankt voor uw aandacht April 3, 2017 Nog vragen? Meer informatie over het Vlaamse e-government en de Coördinatiecel Vlaams e-government: http://www.vlaanderen.be/e-government/ 6 september 2011