MAGDA standaarden & richtlijnen

Presentatie over: "MAGDA standaarden & richtlijnen"— Transcript van de presentatie:

1 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:

2 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

3 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

4 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

5 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)

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

7 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

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

9 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

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

11 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)

12 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

13 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”

14 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”

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

16 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

17 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 ?

18 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 ?

19 Diensten Vlaamse bronnen
VOP entiteit volgens mij alleen binnen Orafin

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

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

22 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.

23 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

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

25 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)

26 Verzoek

27 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

28 Repliek

29 wsdl sjabloon

30 wsdl sjabloon <wsdl:service name=“GeefA">
<wsdl:port name="webServiceHttpPort" binding="webServiceHttpBinding"> <soap:address location=" </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>

31 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

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

33 Domeinen : principe

34 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

35 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

36 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

37 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=" Prefix zonder versieaanduiding Uitzondering: indien meerdere versie van 1 domein gebruikt in de service Namespace met versieaanduiding

38 Generiek: partijen in het bericht

39 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

40 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 ?

41 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)

42 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?

43 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

44 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

45 Naamgeving (Element, Types, …)
Upper Camel Case / Pascal Case (NAAM009) ISO (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>

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

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

48 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

49 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

50 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

51 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

52 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>

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

54 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

55 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

56 Standaarden protocols

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

58 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

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