Coördinatiecel Vlaams e-government MAGDA standaarden & richtlijnen Coördinatiecel Vlaams...

Coördinatiecel Vlaamse-government

MAGDAstandaarden &

richtlijnenCoördinatiecel Vlaams e-government (CORVE)

Lieven Verreycken, SOA Consultant Architect (HB)

Hans Arents, Senior Adviseur (CORVE)

Web: http://www.vlaanderen.be/e-government/

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

Diensten

Bronnen

Afnemers

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 gebruiken2006 2007 2008 2009 2010 2011

0

10

20

30

40

50

60

afnemers

diensten

2006 2007 2008 2009 2010 20110

5,000,000

10,000,000

15,000,000

20,000,000

25,000,000

30,000,000

transacties


Afnemers en bronnenAfnemer: organisatie

Diensten

Federale Bron KSZKBO

VKBO

RepertoriumKoppeltabel

BronAfgeleid

NBB RSZ

CRABx KBO

Repertoria

VlaamseBron

CRAB

RR

LED (Bewijzen)

RUP

DBA

InfoReg

VOPEntiteit CREON

CJSM DAR

MOW

WVG EWI LNE ALV

O&V RWO WSE F&B

...

BZ

Lokalebesturen

Federaal(Kinderbijslag, …)

IV

Graydon ...


Bronnen en soorten dienstenAfnemer

Diensten

Bronnen

VraagAntwoord

Geef - Zoek

RegistreerPublicatie

VraagAntwoord

Geef - Zoek

Registreer Publicatie

4-ogen

Lokalebesturen

FederaalVlaamse

Agentschappen en administraties

Vlaamsebronnen

FederaalMAGDA repertoria

Kruispuntbank

Standaard “soorten” diensten

Met respectievelijke naamgeving


Functionele domeinen

Voorbeeld toepassingen oa met “early adopters”

italic : gepland

Afnemer: toepassingen

Diensten : Domeinen

OndernemingOnderneming xAdres Locatie

Persoon

Werk

Onderwijs

(Repertoria)

Info VOPEntiteit

LED (Bewijzen)

RUP

CREON

CIBCJSM

ORAFINDeLijn

DOMINO

INKOMEWI

EFRO

EPB

ALVAgrilink

CLB

O&V

StudieToelage

AWVPHP

WSE DPOL WSE Inspect

ESFAWAPMIA

SYNTRAVlaanderen

Privacy gevoelig

Bron

DBA

VDAB


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

Diensten

GeefOnderneming

GeefOndernemingOpTijdstip

GeefPersoon

GeefHistoriekPersoon

CreeerBIS

GeefGezinssamenstelling

WijzigKSZPersoon

ZoekPersoonOpAdres

ZoekPersoonOpNaam

GeefJaarrekening

GeefJRKOpTijdstip

GeefTewerkstelling

GeefPCenTW

GeefBeschikbareJRK

GeefAttestLoop-baanonderbreking

BeheerAttestLerende

Inschrijving

GeefDmfAvoorWerknemer

GeefStatuutRVV

GeefLeefloonperiodes

ZoekOnderneming

GeefVestigingen

GeefActiviteiten

GeefHoedanigheden

GeefFuncties

GeefFiscaleInhoudingsplicht

RegistreerDossierOnderneming

VerwijderDossierOnderneming

RegistreerInschrijving

RegistreerDossierPersoon

GeefAdressenLocatiesCRAB

Bron

RegistreerUitschrijving

GeefWerkrelaties

Afnemer

GeefInkomen

GeefHandicap


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

Diensten

GeefInfo

GeefHistoriekInfoDetail GeefVOPEntiteit

GeefBewijs

RegistreerBewijsGeefInfoDetail

GeefHistoriekInfo

InfoReg

BronVOP

Entiteit

ZoekVOPEntiteit

GeefRUP

ZoekRUP

LED RUP

DBA.GeefDossier

DBA.GeefEvent

DBA….

DBA

RegistreerInfo

CREONGateway

CREON

Afnemer

AnnuleerBewijs


Geef – Publiceer Diensten

Diensten : Geef en Publiceer

GeefOnderneming GeefPersoon

GeefAttestLoop-baanonderbreking

GeefDmfAvoorWerknemer

GeefVestigingen

GeefActiviteiten

Bron

Afnemer

PubliceerOnderneming

PubliceerVestigingen

PubliceerActiviteiten

Publiceer(Mutatie)Persoon

Publiceer(Mutatie)Loopbaanonderbr..

Publiceer(Mutatie)DmfAvoorWerkn...

GeefBewijsPubliceer(Mutatie)

Bewijs

Onderneming

Vestiging

Activiteit

... ......

Persoon

AttestLoopBaanonderb...

DmfAvoorWerknemer

Bewijs


Standaard Objecten in vraag-antwoord services en publicaties zijn dezelfde

Voordeel– Consistentie voor de afnemer


Diensten met eenduidig begrippenkader

Diensten

Afnemer

OndernemingOnderneming xAdres Locatie

Persoon

Werk

Leren

Repertoria Info

VOPEntiteit LED (Bewijzen)

RUP

DBA

CREON

Bron

KSZKBO NBB RSZRepertoria

FedICTRR LED RUPKBI

VOPEntiteit CREON

INSZOndernemings

nummer

CBENumber

CBENr

SSINNationalNr

INSZ INSZEntNr

Ondernemingsnummer

Ondernemingsnummer

INSZ

CBENr

PersonNr


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)

– 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• Vroeger 1000, nu onbeperkt

– “Service” folder


Domeinen : principe

Onderneming Persoon

Generiek

Sleutel

Lerende Werk

Adres

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


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

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

– 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

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


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

– 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

Magda

Afnemer

MagdaBusinessDienst 1.0

Magda Gateway 2.0

LED, KBI,…

BusinessDienst

KSZBusiness

Dienst

MagdaBusinessDienst 2.0

KSZ, RR,...

BusinessDienst

Bestaande architectuur

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


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 protocolsDiensten

Intranet (vonet,gid,hostnet)

Privacygevoelig

Publiek

https

Internet Bron

Afnemer

Afnemer

.vonet url

http

https

vipftp.vlaanderen.be

sftp vipftps.vonet.be

ftp

ftp

.vlaanderen url

.vonet url

vipftp.vlaanderen.be


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

Nog vragen?

Meer informatie over het Vlaamse e-government

en de Coördinatiecel Vlaams e-government:



Coördinatiecel Vlaams e-government MAGDA standaarden & richtlijnen Coördinatiecel Vlaams...

Documents

Transcript of Coördinatiecel Vlaams e-government MAGDA standaarden & richtlijnen Coördinatiecel Vlaams...