1        Waarom nieuwe diensten?

MAGDA bouwt een nieuwe versie van het merendeel van de diensten binnen het domein ‘Persoon’. Alle consultatie-, creatie- en wijzigingsdiensten zijn geïmpacteerd, evenals de mutatiediensten m.u.z. van de notificatiediensten.

De belangrijkste reden voor de bouw van de nieuwe diensten is de overschakeling bij de Kruispuntbank Sociale Zekerheid (KSZ) van de ‘V3’ naar de ‘V4’ registers online webservices en publicaties. De nieuwe KSZ-versie werd hoofdzakelijk ontwikkeld voor de volgende nieuwigheden:

• Introductie van het contactadres in de KSZ-registers
• Minimale persoonsgegevens i.p.v. verrijking
• Standaardisatie van de KSZ-webservices

Uit de analyse binnen MAGDA is gebleken dat deze wijzigingen brekend zijn en het niet mogelijk was om de huidige persoonsdiensten-02.00 backwards compatible te houden, zoals we dit de voorbije 8 jaar wel hebben kunnen doen, ondanks de regelmatige wijzigingen bij de bronnen. Bijgevolg is de bouw van nieuwe diensten een noodzaak.

MAGDA maakt tevens van de gelegenheid gebruik om enkele optimalisaties door te voeren aan de structuur van de webservices en kiest voor duidelijke, functionele elementen. Er worden ook enkele nieuwe elementen geïntroduceerd, zoals de ontbrekende wettelijke informatietypes uit het Rijksregister en het OSLO-adres.

We trachten hierbij de impact voor de afnemers zo minimaal mogelijk te houden. Desalniettemin zullen jullie ook de nodige aanpassingen dienen uit te voeren in jullie applicaties.

2         Wat wijzigt er?

2.1      Bronaanpassingen bij de KSZ

2.1.1        Toevoeging van het contactadres

De Kruispuntbank Sociale Zekerheid (KSZ) voert een nieuw adrestype in in haar registers, het contactadres. De buitenlandse adresinformatie die in de huidige manier van werken van de KSZ in het element ‘Hoofdverblijfplaats’ opgeslagen wordt, wordt ook "misbruikt" om tijdelijke verblijven in België op te slaan. In de toekomst zal het contactadres gebruikt worden om de tijdelijke verblijven in België op te slaan en zal KSZ controleren dat geen Belgische adressen meer in het element ‘Hoofdverblijfplaats’ opgeslagen kunnen worden. Om de bestaande toestand recht te trekken zullen tussen 27 en 30 september 2019 ongeveer 400.000 tijdelijke Belgische verblijven gemigreerd worden naar het contactadres, de zgn. 'big bang' (zie ook 3. Migreren?).

De toevoeging van het contactadres heeft impact op onderstaande diensten, maar is beperkt tot opvragingen van personen in de KSZ-registers, zoals het RAD- en BIS-register:

• GeefPersoon
• GeefHistoriekPersoon
• GeefGezinssamenstelling
• GeefHistoriekGezinssamenstelling
• ZoekPersoonOpAdres
• ZoekPersoonOpNaam
• CreëerBIS
• WijzigKSZPersoon
• PubliceerMutatiePersoon
• PubliceerMutatieGezinssamenstelling

2.1.2        Minimale persoonsgegevens i.p.v. verrijking

De KSZ heeft voor bepaalde diensten gekozen voor minimale persoonsgegevens i.p.v. verrijking, dit o.a. omwille van performantie, privacy (proportionaliteit) en relevantie (niet alle gegevens nodig). Dit betekent dat verschillende datablokken, zoals bijvoorbeeld Overlijden, Nationaliteiten, Geboorteplaats en BurgerlijkeStaten, zullen verdwijnen en dat voor bepaalde diensten het Overlijden zal beperkt worden tot een boolean (ja/neen).

Dit heeft impact op volgende diensten:

• ZoekPersoonOpNaam
  • INSZ
  • Geslacht & geboortedatum
  • Naam & voornamen
  • Adres (incl. contactadres) & beheerder
  • IsOverleden (deceased=”true”)
• ZoekPersoonOpAdres
  • INSZ
  • Geslacht & geboortedatum
  • Naam & voornamen
  • Adres & beheerder
  • (Geen overleden personen mogelijk)
• CreëerBIS en WijzigKSZPersoon
  • INSZ
  • Geslacht & geboortedatum
  • Naam & voornamen
  • Adres (incl. contactadres) & beheerder
  • IsOverleden (deceased=”true”)
• GeefGezinssamenstelling en GeefHistoriekGezinssamenstelling
  • INSZ of fictief nummer
  • Geslacht
  • Naam & voornamen
  • Adres enkel voor gezinshoofd, enkel actueel

2.1.3        Kleinere wijzigingen

• Toevoegen van het type register “RAN” (Register der geannuleerden)
• Verlenging naamsveld (familienaam) van 48 naar 128 tekens
• Uitbreiding gezinssamenstelling:
  • Aantal gezinssamenstellingen 50 -> 250
  • Aantal gezinsleden 25 -> 250
  • Aantal gezinshoofden 50 -> 250
• Toevoegen van BeSt Add-adresgegevens door KSZ (nog niet actief)
• Toevoegen isFictief attribuut aan het INSZ-nummer voor fictieve INSZ-nummers gebruikt door KSZ
• Toevoegen nieuwe Uitzonderingcodes wegens nieuwe anomalieën KSZ

2.2      Wijziging van de structuur van de XSD-bestanden

Om de structuur in de XSD-bestanden te optimaliseren, wordt ze vereenvoudigd en zal ze gebaseerd zijn op functie i.p.v. op type element. Dit betekent initieel meer werk, maar maakt het voor jullie, afnemers, eenvoudiger om nieuwe structuren te gebruiken en gemakkelijker om te migreren. Ook het onderhoud van applicaties wordt eenvoudiger.

Dit heeft impact op alle persoonsdiensten-02.02.

2.3      Wijziging van de namespace van de XSD-bestanden

De namespaces van de XSD-bestanden waren verouderd. Deze zijn vernieuwd en consistent gemaakt met een betere, logische structuur.

Dit heeft impact op alle persoonsdiensten-02.02.

2.4      Implementatie OSLO-adres

MAGDA wil inzetten op semantische interoperabiliteit en zal zich hiervoor enten op de OSLO-standaarden. Er is gekozen om in eerste instantie het OSLO-adres te implementeren in de persoonsdiensten-02.02.

Een adres is in de eerste plaats een op zichzelf staand object met een eigen identificator en levensloop. Dat geldt ook voor adrescomponenten zoals straatnaam en gemeentenaam. Het adresobject dat zo ontstaat noemen we een gestructureerd adres. In tweede orde is een adres een attribuut, bv. het adres van een gebouw of een adreslabel op kaart. Het is in dat geval niet nodig om het adres te structureren, een opsomming van zijn componenten volstaat. Dit is de zgn. adresvoorstelling.

MAGDA zal in de persoonsdiensten-02.02 een uitgebreide OSLO-adresvoorstelling implementeren en niet de volledige OSLO-structuur. Deze OSLO-adresvoorstelling bevat dezelfde data als het huidige MAGDA-adres. De structuur is echter vlakker. Daarnaast zal de uitgebreide OSLO-adresvoorstelling de nodige (BeSt Add) ID’s bevatten, waarmee, indien gewenst, het gestructureerd OSLO-adres kan opgevraagd worden via de webservices van BOSA of het Vlaamse adressenregister.

Door nu reeds over te schakelen naar deze nieuwe adresvoorstelling, worden nieuwe aanpassingen vermeden, na het invoeren van de BeSt Add-gegevens in 2020.

Een vergelijking van de mapping voor de hoofdverblijfplaats tussen de GeefPersoon 2.0 en GeefPersoon 02.02 is te vinden in onderdeel "OSLO adressenstructuur" op de pagina  Verschillen met vorige versie.

2.5      Toevoeging wettelijke informatietypes

Voor elke persoon in het Rijksregister worden verschillende informatiegegevens bijgehouden, onderverdeeld in verschillende informatietypes. Deze informatietypes (IT) karakteriseren het administratief statuut van een persoon en kunnen wijzigingen in de loop van zijn leven.

De ‘wettelijke’ informatiegegevens, zijn de gegevens bedoeld in artikel 3, eerste en tweede lid, van de wet van 8 augustus 1983. De in de MAGDA-persoonsdiensten nog ontbrekende informatietypes die behoren tot deze ‘wettelijke’ informatiegegevens, zullen toegevoegd worden in de persoonsdiensten-02.02.

Dit heeft impact op onderstaande diensten:

• GeefPersoon
• GeefHistoriekPersoon
• PubliceerMutatiePersoon

2.6      Toevoeging extra data vanuit KSZ

Bij de Kruispuntbank Sociale Zekerheid (KSZ) is de extra persoonsinformatie opgesplitst in verschillende diensten. Om deze informatie uit te breiden - en daardoor meer in lijn te komen met de informatie die ontvangen wordt vanuit het Rijksregister - zullen ook de bijkomende KSZ-diensten, die informatie geven uit het wachtregister, over buitenlanders (beroepskaart, arbeidskaart, wettig verblijf), afstamming in dalende en stijgende lijn en identiteitsbewijzen, aangeroepen worden. Daarnaast is het oproepen van de basisgegevens ook een optionele opvraging geworden bij de KSZ. Het is echter noodzakelijk om bij het gebruik van 'KSZ' als bron minimaal 1 element onder OpvragingenKSZ aan te duiden in de vraag.

Deze uitbreiding heeft geen impact op de structuur van het XSD-schema. Er wordt enkel meer informatie doorgegeven bij het gebruik van ‘KSZ’ als bron, indien je daarvoor de nodige toelating(en) hebt.

Dit heeft impact op onderstaande diensten:

• GeefPersoon

Deze uitbreiding werd geïnitieerd vanuit Kind & Gezin. Dit om het mogelijk te maken om eerst de basisgegevens op te vragen en daarna, gescheiden, extra informatie op te vragen over deze persoon zonder dat de basis persoonsgegevens opnieuw moeten opgevraagd.
Indien je hierin interesse hebt, vragen we je om de MAGDA Helpdesk te contacteren via helpdesk.magda@vlaanderen.be.

3         Migreren?

KSZ plant de 'big bang', de migratie van de Belgische adressen uit 'hoofdverblijfplaats' naar 'contactadres', op 27 september 2019. De uitrol zal starten om 17u, de gegevensmigratie zal aansluitend starten en zal het ganse weekend in beslag nemen. De diensten blijven beschikbaar zowel voor consultatie als voor creatie en bijwerkingen, maar bijwerkingen van tijdelijke Belgische adressen zullen falen voor data die nog niet gemigreerd zijn.

Dit betekent dat in principe afnemers die voor die datum niet naar de nieuwe 02.02-diensten zijn gemigreerd, de Belgische adressen van personen uit het BIS- of RAD-register niet meer kunnen raadplegen, geen BIS-nummers meer kunnen aanmaken met een Belgisch adres en geen hoofdverblijfplaats meer kunnen bijwerken met een Belgisch adres. Echter om elke onderbreking in de dienstverlening te vermijden, heeft KSZ eind augustus 2019 beslist om alsnog hun bestaande diensten, waarvan de MAGDA-02.00-diensten gebruik maken, aan te passen, opdat ze bijna zoals "nu werken", ook na de migratie van de Belgische adressen naar het blok contactadres. Bijna, omdat er niettemin een aantal beperkingen bestaan, zoals het feit dat de raadplegingsdiensten van de historiek nooit rekening houden met de contactadressen in de historiek van de hoofdverblijfplaats of dat het niet mogelijk is om een adres bij te werken met een Belgisch adres wanneer er reeds een adres in het buitenland bestaat.

Impact op de MAGDA-02.00-diensten: regels van toepassing na de 'big bang'

GeefPersoon-02.00 en GeefHistoriekPersoon-02.00

• bij de raadpleging van een BIS/RAD-nummer met enkel een contactadres, wordt dit contactadres opgestuurd;
• bij de raadpleging van een BIS/RAD-nummer met enkel een verblijfsadres, wordt dit verblijfsadres opgestuurd;
• bij de raadpleging van een BIS/RAD-nummer met een verblijfsadres én een contactadres, wordt enkel het verblijfsadres opgestuurd;

GeefHistoriekPersoon-02.00

• bij de raadpleging van de historiek van een BIS/RAD-nummer, worden enkel de adressen in het buitenland verstuurd. Het is immers veel te complex om een historiek aan te maken met adressen in het buitenland en met contactadressen. De diensten “historiek” worden dus niet aangepast en compatibel gemaakt.

ZoekPersoonOpNaam-02.00

• bij de fonetische opzoeking is er geen impact, het (contact)adres is hierbij niet van belang
• er gebeurt een "verrijking" van de resultaten met de personen alsof ze geconsulteerd werden, dus de mapping van het contactadres naar adres zal gebeuren zoals hierboven beschreven voor GeefPersoon-02.00.

ZoekPersoonOpAdres-02.00

• geen impact, geeft enkel resultaten terug van personen die hun huidige hoofdverblijfplaats in België hebben (Rijksregister).

CreëerBIS-02.00

• bij de aanmaak van een BIS-nummer wordt, wanneer de aanvrager een Belgisch adres aangeeft, dit adres ingebracht in het dossier van het BIS-nummer als een contactadres van het type “onbepaald”.

WijzigKSZPersoon-02.00

• indien men bij de bijwerking een adres in het buitenland wenst toe te voegen/te wijzigen, wordt deze aanvraag aanvaard (volgens de bestaande voorwaarden) en indien er een contactadres bestaat, blijft dit adres ongewijzigd en actief.
• indien men bij de bijwerking een adres in België wenst toe te voegen/te wijzigen en er geen adres in het buitenland en geen contactadres bestaat of indien er geen adres in het buitenland maar wel een contactadres bestaat, dan wordt de aanvraag aanvaard (volgens de bestaande voorwaarden).
• indien men bij de bijwerking een adres in België wenst toe te voegen/te wijzigen en er een adres in het buitenland bestaat, dan wordt de aanvraag geweigerd. 

PubliceerMutatiesPersoon-02.00

• bij aanmaak/wijziging van een verblijfsadres en zelfs indien er een contactadres bestaat, wordt een mutatie met het verblijfsadres verstuurd;
• bij aanmaak /wijziging van een contactadres, terwijl er reeds een verblijfsadres bestaat, wordt geen mutatie verstuurd;
• bij wijziging van een contactadres en indien er geen verblijfsadres bestaat, wordt een mutatie verstuurd.

Samengevat, het verblijfsadres primeert op het contactadres maar er worden mutaties verstuurd in verband met het contactadres indien er geen verblijfsadres bestaat.

Tijdens de migratie van de Belgische adressen, worden mutaties m.b.t. adreswijzigingen verstuurd, ook al blijkt er niets gewijzigd te zijn.

Indien je in je business processen dus (tijdelijke) Belgische adressen van personen in de KSZ-registers (BIS-, RAD- en RAN-register) nodig hebt, is het aangeraden zo snel mogelijk te migreren naar de nieuwe 02.02-diensten. Afnemers die deze gegevens niet (onmiddellijk) nodig hebben, kunnen de overstap nog even uitstellen. Let wel, de huidige 02.00-diensten ondersteunen we tot september 2020. Alle afnemers zullen dus voor deze datum moeten aansluiten op de nieuwe 02.02-diensten. De concrete timing zal afhankelijk zijn van afnemer tot afnemer. Contacteer hiervoor de MAGDA Helpdesk via helpdesk.magda@kb.vlaanderen.be. We bekijken vervolgens met jou de concrete planning.

4         Documentatie

De specificaties van de nieuwe diensten zijn beschikbaar in de MAGDA Gebruikersomgeving. Je zal hier ook steeds de meest recente informatie over dit project terugvinden:

• Algemene informatie
• XSD’s
• Handleidingen

5         Vragen of problemen?

Vragen of problemen m.b.t. de 02.02-diensten kunnen gemeld worden via de Kruispuntbank Vlaanderen Service Desk – ‘testing persoonsdiensten-02.02’: (https://vlaamseoverheid.atlassian.net/servicedesk/customer/portal/9/group/13/create/142).