MAGDA standaarden & richtlijnen

1. MAGDAstandaarden & 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/

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

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

11. Functionele domeinen Voorbeeld toepassingen oa met “early adopters” italic : gepland

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

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

20. Geef – Publiceer Diensten

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

22. Diensten met eenduidig begrippenkader

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) • 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="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>

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 • 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="http://generiek-02_00.vip.vlaanderen.be" • 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 • 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 • Componenten • (Elementen, Types, …) • Naamgeving (13) • Definitie (15) • Ontwerp (11) • Schema • Taal (1) • Industrie standaarden (5) • Modulariteit (9) • Structuur (1) • Namespace (8) • Versie (3) • Andere (2) • Document “CORVE_VIP_Richtlijnen_XML_Schema”

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

46. Collections • Afzonderlijk element voor de collection • 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 • In principe verplicht • Optioneel wegens uitzonderlijkniet ingevuld door bron  • NIS Straat code • Idem cfr supra • NIS gemeente code • CRAB straat code • Adres Internationaal

49. Beschrijving - omschrijving • Beschrijving • 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