Transcript Werkgroep MAGDA richtlijnen en standaarden

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/
Coördinatiecel Vlaams
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
Coördinatiecel Vlaams
e-government
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
Coördinatiecel Vlaams
e-government
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
Coördinatiecel Vlaams
e-government
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)
Coördinatiecel Vlaams
e-government
MAGDA: basis begrippen
 Vereenvoudigd model en terminologie
– Afnemers: ook leveranciers
 “kapstok” voor verdere verfijning
Afnemers
Diensten
Bronnen
Coördinatiecel Vlaams
e-government
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
Coördinatiecel Vlaams
e-government
Impact van wijziging op standaard
 Gebruik – dienst gemiddeld door 5,5 afnemers gebruikt
60
30,000,000
50
25,000,000
40
20,000,000
30
20
afnemers
15,000,000
diensten
10,000,000
transacties
5,000,000
10
0
0
2006
2006
2007
2008
2009
2010
2007
2008
2009
2010
2011
 Impact op alle afnemers die de diensten gebruiken
Coördinatiecel Vlaams
e-government
2011
Afnemers en bronnen
Afnemer: organisatie
CJSM
Federaal
(Kinderbijslag, …)
DAR
MOW
WVG
O&V
EWI
RWO
LNE
WSE
ALV
F&B
IV
Lokale
besturen
BZ
Diensten
Bron
Afgeleid
Repertorium
Koppeltabel
VKBO
CRAB
x KBO
LED (Bewijzen)
VOP
Entiteit
Federale
Bron
KBO
RR
Gray
don
RSZ
Info
Reg
CREON
RUP
KSZ
CRAB
NBB
Coördinatiecel Vlaams
e-government
Reper
toria
Vlaamse
Bron
DBA
...
...
Bronnen en soorten diensten
Afnemer
Federaal
Vlaamse
Agentschappen en administraties
Lokale
besturen
Diensten
4-ogen
Vraag
Antwoord
Geef - Zoek
Registreer
Publicatie
Vraag
Antwoord
Geef - Zoek
Registreer
Bronnen
Federaal
MAGDA repertoria
Kruispuntbank
 Standaard “soorten” diensten
 Met respectievelijke naamgeving
Coördinatiecel Vlaams
e-government
Vlaamse
bronnen
Publicatie
Functionele domeinen
Afnemer: toepassingen
ORAFIN
CIB
CJSM
DOMINO
INKOM
EWI
EFRO
EPB
ALV
Agri
link
De
Lijn
CLB
O&V
Studie
Toelage
AWV
PHP
WSE DPOL
MIA
WSE Inspect
AWAP
Diensten : Domeinen
Persoon
Werk
(Repertoria)
Onderneming x
Adres Locatie
RUP
CREON
Info
Bron
Voorbeeld toepassingen oa met “early adopters”
Coördinatiecel Vlaams
e-government
VDAB
LED (Bewijzen)
Onderwijs
italic : gepland
ESF
DBA
Privacy gevoelig
Onderneming
SYNTRA
Vlaanderen
VOPEntiteit
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
Coördinatiecel Vlaams
e-government
Naamgeving diensten
Afnemer
Diensten
GeefJaarrekening
GeefPersoon
GeefOnderneming
ZoekOnderneming
GeefVestigingen
GeefOnderneming
OpTijdstip
GeefStatuutRVV
GeefJRK
OpTijdstip
GeefHistoriek
Persoon
GeefBeschikbare
JRK
CreeerBIS
Geef
Tewerkstelling
GeefActiviteiten
GeefLeefloon
periodes
WijzigKSZPersoon
GeefGezins
samenstelling
Geef
Hoedanigheden
ZoekPersoon
OpAdres
GeefFuncties
ZoekPersoon
OpNaam
Bron
Coördinatiecel Vlaams
e-government
VerwijderDossier
Onderneming
GeefWerkrelaties
GeefAdressen
LocatiesCRAB
Registreer
Inschrijving
GeefAttestLoopbaanonderbreking
GeefDmfA
voorWerknemer
GeefPCenTW
GeefFiscale
Inhoudingsplicht
RegistreerDossier
Onderneming
BeheerAttest
Lerende
Inschrijving
Geef
Inkomen
Registreer
Uitschrijving
RegistreerDossier
Persoon
Geef
Handicap
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”
Coördinatiecel Vlaams
e-government
Naamgeving
 Toegepast op / vertaald naar technische services
– Webservice
• 1 naam – 1 dienst – 1 operatie
– FTP
• Geen operatie
Coördinatiecel Vlaams
e-government
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
Coördinatiecel Vlaams
e-government
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 ?
Coördinatiecel Vlaams
e-government
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 ?
Coördinatiecel Vlaams
e-government
Diensten Vlaamse bronnen
Afnemer
Diensten
GeefInfo
GeefBewijs
DBA.GeefDossier
GeefInfoDetail
RegistreerBewijs
DBA.GeefEvent
GeefHistoriekInfo
AnnuleerBewijs
DBA….
GeefHistoriek
InfoDetail
GeefVOPEntiteit
GeefRUP
RegistreerInfo
ZoekVOPEntiteit
ZoekRUP
CREON
Gateway
Bron
Info
Reg
Coördinatiecel Vlaams
e-government
VOP
Entiteit
LED
RUP
DBA
CREON
Geef – Publiceer Diensten
Afnemer
Diensten : Geef en Publiceer
GeefOnderneming Onderneming
Publiceer
Onderneming
GeefVestigingen
Vestiging
Publiceer
Vestigingen
GeefActiviteiten
Activiteit
Publiceer
Activiteiten
...
...
...
GeefBewijs
Bron
Coördinatiecel Vlaams
e-government
GeefPersoon
Persoon
Publiceer(Mutatie)
Persoon
Publiceer(Mutatie)
GeefAttestLoopAttestLoop
baanonderbreking Baanonderb... Loopbaanonderbr..
GeefDmfA
voorWerknemer
Bewijs
DmfAvoor
Werknemer
Publiceer(Mutatie)
Bewijs
Publiceer(Mutatie)
DmfAvoorWerkn...
Standaard
 Objecten in vraag-antwoord services en publicaties zijn dezelfde
 Voordeel
– Consistentie voor de afnemer
Coördinatiecel Vlaams
e-government
Diensten met eenduidig begrippenkader
Afnemer
Ondernemings
nummer
Diensten
INSZ
Persoon
Repertoria
Info
DBA
Onderneming
Onderneming x
Adres Locatie
Werk
VOPEntiteit
LED (Bewijzen)
Leren
RUP
Ondernemings
nummer
CREON
INSZ
Bron
CBE
Number
CBE
Nr
KBO
NBB
Ent
Nr
RSZ
Coördinatiecel Vlaams
e-government
National
Nr
RR
CBE
Nr
SSIN
KSZ
Person
Nr
Fed
ICT
Ondernemings
nummer
Reper
VOP
KBI
toria
Entiteit
INSZ
LED
INSZ
RUP
CREON
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
Coördinatiecel Vlaams
e-government
Standaard
 Naamgeving
 wsdl – xsd – url
 Folder structuur van de specificatie
 Types en elementen: generiek en voor functionele domeinen
 Versiebeheer in de specificatie
 xsd modellering
Coördinatiecel Vlaams
e-government
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)
Coördinatiecel Vlaams
e-government
Verzoek
Coördinatiecel Vlaams
e-government
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
Coördinatiecel Vlaams
e-government
Repliek
Coördinatiecel Vlaams
e-government
wsdl sjabloon
Coördinatiecel Vlaams
e-government
wsdl sjabloon
<wsdl:service name=“GeefA">
<wsdl:port name="webServiceHttpPort" binding="webServiceHttpBinding">
<soap:address location="https://magdadienst.vlaanderen.be/MagdaDienst02.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>
Coördinatiecel Vlaams
e-government
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
Coördinatiecel Vlaams
e-government
FTP variant
 FTP variant
– Meerdere vragen / antwoorden
• Vroeger 1000, nu onbeperkt
– “Service” folder
Coördinatiecel Vlaams
e-government
Domeinen : principe
Sleutel
Generiek
Onderneming
Lerende
Coördinatiecel Vlaams
e-government
Persoon
Adres
Werk
...
Vergunning
Bewijs
...
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
Coördinatiecel Vlaams
e-government
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
Coördinatiecel Vlaams
e-government
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
Coördinatiecel Vlaams
e-government
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
Coördinatiecel Vlaams
e-government
Generiek: partijen in het bericht
Coördinatiecel Vlaams
e-government
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
Coördinatiecel Vlaams
e-government
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 ?
Coördinatiecel Vlaams
e-government
Richtlijnen schema – xsd modellering
 Schema
– Taal (1)
 Componenten
(Elementen, Types, …)
– Industrie standaarden (5)
– Naamgeving (13)
– Modulariteit (9)
– Definitie (15)
– Structuur (1)
– Ontwerp (11)
– Namespace (8)
– Versie (3)
– Andere (2)
 Document “CORVE_VIP_Richtlijnen_XML_Schema”
Coördinatiecel Vlaams
e-government
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?
Coördinatiecel Vlaams
e-government
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
Coördinatiecel Vlaams
e-government
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
Coördinatiecel Vlaams
e-government
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>
Coördinatiecel Vlaams
e-government
Collections
 Afzonderlijk element voor de collection
– ipv unbounded rechtstreeks binnen het bovenliggende Type
 Voordeel
– Leesbaarheid
– Code generatie
– Parsing
Coördinatiecel Vlaams
e-government
Typering
 Steeds Types voor de elementen binnen ComplexType
– Complex of Simple
 Any Type: slechts uitzonderlijk toegelaten
 Aantal SimpleType voor strings
 Voordeel
– Leesbaarheid
Coördinatiecel Vlaams
e-government
Generiek
 Adres uit 1.2
– Straat, gemeente
• In principe verplicht
• Optioneel wegens uitzonderlijk
niet ingevuld door bron 
– NIS Straat code
• Idem cfr supra
– NIS gemeente code
– CRAB straat code
– Adres Internationaal
Coördinatiecel Vlaams
e-government
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
Coördinatiecel Vlaams
e-government
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
Coördinatiecel Vlaams
e-government
Datums en tijd
 Tijdstip Type
– Tijd en Datum
 Creatie en modificatie datum van object
 Periodes
– Begindatum en Einddatum
• 4 combinaties verplicht – optioneel in 2.0
Coördinatiecel Vlaams
e-government
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>
Coördinatiecel Vlaams
e-government
Wijzigingen 2.0 tov 1.x
 Doelstellingen
– gateways
– redundante systemen voor
hogere beschikbaarheid
 Contract van gateway
en directe business
dienst na gateway zijn gelijk
Afnemer
Magda
Magda Gateway 2.0
Magda
Business
Dienst 1.0
KSZ
Business
Dienst
Bestaande
architectuur
Coördinatiecel Vlaams
e-government
Magda
Business
Dienst 2.0
KSZ, RR,
...
Business
Dienst
LED, KBI,
…
Business
Dienst
Doel
architectuur
Wijzigingen 2.0 tov 1.x
 Referte
– 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
Coördinatiecel Vlaams
e-government
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
Coördinatiecel Vlaams
e-government
Standaarden protocols
Internet
https .vlaanderen url
ftp
Bron
Diensten
vipftp.vlaanderen.be
Publiek
Afnemer
Intranet
(vonet,
gid,
hostnet)
http
.vonet url
ftp
vipftp.vlaanderen.be
Afnemer
https .vonet url
sftp
Coördinatiecel Vlaams
e-government
vipftps.vonet.be
Privacy
gevoelig
Standaard formulier aansluiting vd afnemer
 Standard formulieren voor aanvraag
 Identificatie aanvrager
 Motivatie
 Machtigingen
– privacy gevoelige diensten
 Validatie in T&I omgeving
 Timing forecast
Coördinatiecel Vlaams
e-government
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
Coördinatiecel Vlaams
e-government
Bedankt voor uw aandacht
Nog vragen?
Meer informatie over het Vlaamse e-government
en de Coördinatiecel Vlaams e-government:
http://www.vlaanderen.be/e-government/
Coördinatiecel Vlaams
e-government