Digimelding-koppelvlakspecificatie

Datum	Versie	Auteur	Opmerkingen
13-02-2015	0.1	Logius	Eerste concept
	0.2
28-10-2015	0.9	Logius	Diverse spellingsverbeteringen.
31-03-2016	0.91	Logius	Aanpassingen n.a.v. bevindingen pilot
30-03-2016	1.0	Logius	Definitief na goedkeuring Afnemersraad
14-05-2018	1.1	Logius	RFC Behandelend Bronhouder
21-11-2019	1.2	Logius	Zie release notes
24-06-2020	1.2.1	Logius	Tekstuele aanpassingen / correcties
01-06-2021	1.3	Logius	RFC-2020-3 - SSOn-Rijk gebruik in Digimelding Portaal


Logius Servicecentrum:	Postbus 96810 2509 JE Den Haag tel. 0900 555 4555 (10 ct p/m) email servicecentrum@logius.nl

Referentiedocument	Bronverwijzing
GEMMA Informatiearchitectuur 1.0	PDF versie op NORA
StUF 3.01	StUF website
StUF protocolbindingen 3.02	StUF website
ArchiMate 2.n	The Open Group Website
DMKS cookiebox	Digimelding pagina op Logius website
Digikoppeling WUS 3.0	Vastgestelde versie 06 oktober 2020
Digikoppeling-architectuur	Vastgestelde versie 07 oktober 2018

Implementatievariant	Specifieke en aanvullende eisen
A1	De terugmeldende ambtenaar maakt gebruik van het landelijke Digimelding Webservice portaal.
A2	De terugmeldende ambtenaar maakt gebruik van een lokaal binnen de organisatie geïnstalleerd terugmeldportaal welke middels webservices communiceert.
A3	De terugmeldende ambtenaar maakt gebruik van een terugmeldoptie binnen zijn taakapplicatie; de taakapplicatie zet deze terugmelding door naar een terugmeldapplicatie binnen de organisatie welke middels webservices communiceert.
B1	De communicatie middels webservices tussen terugmeldende organisatie en landelijke voorziening van een basisregistratie loopt via een webservices koppelvlak op de Digimelding Webservice, als landelijke voorziening. Deze landelijke voorziening verzorgt routering naar basisregistraties (en mogelijk protocoltransformatie naar een vorige of volgende versie van het koppelvlak).
B2	De communicatie middels webservices tussen terugmeldende organisatie en landelijke voorziening van een basisregistratie loopt rechtstreeks (staat niet geïllustreerd in referentieplaatje hierboven).

Autorisatie
Terugmelder	Terugmeld Applicatie	Digikoppeling Adapter	TMV Basisregistratie
E-herkenning in DMKS bericht OIN Vestigingsnr Persoonsaanduiding	OIN in DMKS bericht	OIN in Digikoppeling Headers WS-Adressing	Transport via Digikoppeling
SSOn Rijk OIN Vestigingsnr Persoonsaanduiding	(PKIO certificaat met OIN voor signing)	PKIO certificaat met OIN voor TLS/signing	Applicatie: via OIN in DMKS bericht of via E-Herkenning : OIN, vestigingsnummer en persoonsaanduiding in DMKS bericht of via SSOn Rijk attributen
Vrije keuze	OIN in Digikoppeling Header WS-security

Dit hoofdstuk beschrijft de berichten tussen terugmeldapplicatie, Digimelding Webservice en de LV van basisregistraties (gerouteerd via Digimelding Webservice)

Het interactiediagram biedt overzicht in hoe de berichten zich tot elkaar verhouden en in welke volgorde de berichten worden gebruikt.

Per bericht wordt aangegeven (indien relevant):

berichtnaam;
trigger van het bericht;
verandering in terugmeldapplicatie/Digimelding Webservice/LV basisregistratie ten gevolge van het bericht;
lijst van objecten en velden in het bericht, en per veld:
- specificatie van de vulling van het veld,
- toelichting, bijvoorbeeld met de gebruikersactie of configuratie die nodig is om de juiste vulling te krijgen.

Tevens wordt bij de berichten een interactiediagram getoond waarin duidelijk wordt welk systeem het bericht initieert.

De Digimelding-koppelvlakspecificatie (DMKS) die de basis vormt voor dit koppelvlak gaat uit van annotaties. Alle informatie over een terugmelding is vastgelegd in de vorm van een annotatie. Hierbij kent de DMKS ook annotatiebomen waarbij root annotaties voorzien zijn van leaf annotaties. De leafs zijn annotaties die een verwijzing bevatten naar de UUID van de root annotatie waar ze aan hangen. In theorie is het mogelijk dat een annotatie tegelijkertijd een root en leaf is, deze annotatie hangt dan aan een andere 'root node' maar heeft zelf ook leafs. Dit laatste komt in de huidige praktijk niet voor.

Iedere annotatie kent een basisset aan elementen: de 'annotatiebasis' Deze worden bij iedere annotatie herhaald waardoor berichten behoorlijk omvangrijk worden. Voor het overzicht wordt deze annotatie basis in de volgende secties met specifieke berichten samengevat tot één regel Annotatiebasis. Hieronder leggen we eenmalig uit welke elementen deze annotatiebasis bevat.

Tabel Annotatiebasis

Parameter	Toelichting	Relaties
@uuid	Unieke identificatie van de annotatie.	[1..1]
GeannoteerdDoor	Gegevens van diegene die de annotatie heeft toegevoegd.	[1..1]
GeannoteerdDoor.Oin	OIN van de terugmeldende organisatie.	[1..1]
GeannoteerdDoor.Vestiging	Vestigingsnummer van desbetreffende organisatie uit eHerkenning/SSOn Rijk (indien door de afnemer toegepast voor authenticatie).	[0..1]
GeannoteerdDoor.Persoonsaanduiding	Deze zal met webservices bijna altijd de waarde "anoniem" hebben. Er zijn twee uitzonderingen. De eerste is wanneer nadere afspraken gemaakt zijn met een basisregistratie over de invulling van dit veld. De tweede is dat, indien binnen de organisatie eHerkenning/SSOn Rijk gebruikt is voor autorisatie en authenticatie, persoonsaanduiding uit eHerkenning/SSOn Rijk dient te worden meegegeven.	[1..1]
GeannoteerdOp	Tijdstempel waarop de annotatie heeft plaatsgevonden.	[1..1]
Toelichting	Een toelichting bij de annotatie. In de huidige praktijk in gebruik voor root annotaties en status leaf annotaties voor overige leaf annotaties in de huidige praktijk altijd leeg.	[0..1]
Annotatieverwijzing	Verwijzing naar de root annotatie waar een leaf annotatie aan gerelateerd is. Dit wordt afhankelijk van de relevantie opgenomen.	[0..1]

De berichten beschreven in deze uitwisseling worden gebruikt om:

met de terugmeldapplicatie van een afnemer een terugmelding te versturen
om een eerder door de afnemer gedane terugmelding in te trekken
om een status terug te melden van een bronhouder naar een Landelijke Voorziening

Term	Toelichting
Doel	Het toevoegen van een annotatie(boom) bij een op Digimelding aangesloten basisregistratie door een (medewerker van) een organisatie. Het effect van het annotatie toevoegen, terugmelden is het doen van een terugmelding. Het effect van een annotatie toevoegen, intrekken is het intrekken van een terugmelding. Het effect van een annotatie toevoegen, statuswijziging is het geven van een statusupdate.
Voorwaarde	Afname van gegevens uit basisregistraties door de terugmeldende organisatie, en het gedaan hebben van een check van de actuele waarde in de basisregistratie bij het doen van een terugmelding. Voor het intrekken van een terugmelding moet er al een terugmelding gedaan is. Voor het verzenden van een statuswijziging moet een terugmelding zijn ontvangen door de bronhouder
Trigger	Gerede twijfel over de juistheid van een gegeven in een op Digimelding aangesloten basisregistratie bij een ambtenaar binnen de organisatie. Het terugkomen op de gerede twijfel van een eerder gedane terugmelding in het geval van intrekken. Het veranderen van een status door middel van een statuswijziging van een terugmelding bij een bronhouder.
Direct gevolg	Versturen van een bericht naar de betreffende bronhouder of landelijke voorziening.
Vervolgactie	De landelijke voorziening van de basisregistratie neemt de terugmelding in behandeling. De gebruiker van de terugmeldende organisatie kan dit volgen middels status opvragen. De landelijke voorziening verwerkt de statusupdate.

Figuur 3 Interactiediagram terugmelden/intrekken direct

Figuur 4 Interactiediagram terugmelden/intrekken via Digimelding Webservice

Figuur 5 Interactiediagram status wijzigen

Tabel AnnotatieToevoegenRequest

Parameter	Toelichting	Relaties
OinBasisregistratie	Het OIN van de houder van een landelijke voorziening van de basisregistratie	[1..1]
Registratie	Code (maximaal 3 letterig) waarmee de basisregistratie wordt aangeduid wanneer de houder van een landelijke voorziening meer dan 1 basisregistratie beheert (bv BRT, BGT).	[0..1]
Annotatie	Dit element wordt alleen gevuld met een annotatie die moet worden ingetrokken.*	[1..1]*
AnnotatieBoom	Bestaat uit minimaal één annotatie (de terugmelding) en de bijbehorende leafs.*	[1..1]*

* De elementen Annotatie en AnnotatieBoom zijn onderdeel van een verplicht keuzeveld: de AnnotatieToevoegenRequest bevat altijd slechts één van de twee.

De structuur van de instanties van 'Annotatie' in de 'AnnotatieBoom' is als volgt:

Tabel AnnotatieBoom.Annotatie

AnnotatieBoom . Annotatie		[1..*]
Annotatie.Terugmelding		[1..1]
Terugmelding.Annotatiebasis
Terugmelding.Bronverwijzingen	Bronverwijzingen bestaande uit één of meerdere bronverwijzing* *Lijst van verwijzingen met basisregistratie elementen waarop wordt teruggemeld.	[1..1]
Terugmelding.Bronverwijzingen. Bronverwijzing	Bestaande uit een URI en een selectieverwijzing naar het basisregistratie-element waarop wordt teruggemeld. Dit zijn er meerdere, maar in de huidige praktijk is dit er altijd precies één.	[1..*]
Terugmelding.Bronverwijzingen. Bronverwijzing.Uri	Een combinatie van OIN en de unieke sleutel van het brongegeven zodat een unieke referentie ontstaat naar het brongegeven (bijv. OIN en HRN).	[1..1]
Terugmelding.Bronverwijzingen. Bronverwijzing.Selectie	Selectie van een element binnen de structuur die door de URI uniek geïdentificeerd wordt (bijvoorbeeld onderneming).	[0..*]
Terugmelding . Attributenset	De set van attributen die daadwerkelijk gewijzigd dienen te worden.	[1..1]
Attribuut	Eén of meerdere attributen die gewijzigd dienen te worden.	[1..*]
Attribuut.Uri	De unieke aanduiding van het attribuut	[1..1]
Attribuut.BetwijfeldeWaarde	De bestaande waarde in de basisregistratie.	[0..1]
Attribuut.VoorgesteldeWaarde	De voorgestelde nieuwe waarde.	[0..1]
Terugmelding . Peilmoment	De datum waarop de betwijfelde waarde geldig is en de voorgestelde waarde geldig zou moeten zijn.	[0..1]

Annotatie.Annotatiestatus	Status van de terugmelding	[1..*]
Annotatiestatus.Annotatiebasis
Annotatiestatus . Status	Zie bijlage B voor lijst met geadviseerde statussen voor aangesloten basisregistraties.(Het is toegestaan om in de eigen catalogus afwijkende statussen op te nemen)	[1..1]

Annotatie.Referentiekenmerk	Eigen kenmerk terugmeldende organisatie (het mogen er meer zijn, in de huidige praktijk altijd precies één).	[1..*]
Referentiekenmerk.Annotatiebasis
Referentiekenmerk.Kenmerk	Eigen kenmerk terugmeldende organisatie.* *In de huidige praktijk maximaal 12 posities	[1..1]

Annotatie.Contactinformatie	Contactgegevens	[1..*]
Contactinformatie.@ContactType	kan alleen de waarden 'Melder' of 'Behandelaar' hebben	[1..1]
Contactinformatie.Annotatiebasis
Contactinformatie.Naam		[1..1]
Contactinformatie.Telefoon		[0..1]
Contactinformatie.Email		[1..1]
Contactinformatie.Afdeling		[0..1]

Annotatie.Bijlageverwijzing	HR ondersteunt maximaal 5 bijlagen.	[0..*]
Bijlageverwijzing.Annotatiebasis
Bijlageverwijzing.Bestandsnaam	De naam van het bestand.	[1..1]
Bijlageverwijzing.MIMEType	Het MIME type van de bijlage.	[1..1]
Bijlageverwijzing.BijlageData	Het bestand zelf in Base64-binary encoding.	[1..1]
Bijlageverwijzing.Beschrijving	Beschrijving van de bijlage. De bijlage zelf wordt nooit mee teruggeleverd bij het bevragen van een terugmelding/annotatie.	[0..1]

Annotatie.BehandelendeBronhouder	Behandelende bronhouder	[0 *]
BehandelendeBronhouder.Annotatiebasis
BehandelendeBronhouder.Bronhouder	De gewenste bronhouder	[1..1]

De volgende structuur is in de XML-structuur child van de 'Annotatie'.

Annotatiestatus	Status van de terugmelding.	[1..*]
Annotatiestatus.Annotatiebasis	Inclusief toelichting en annotatieverwijzing
Annotatiestatus.Status	Een afnemer kan bij het doen van een intrekking alleen de status: INGETROKKEN gebruiken in de huidige praktijk.	[0..1]

Annotatie toevoegen (statuswijziging) De volgende structuur is in de XML-structuur child van de 'Annotatie'.

Annotatiestatus	Status van de terugmelding.	[1..*]
Annotatiestatus.Annotatiebasis	Inclusief toelichting en annotatieverwijzing
Annotatiestatus.Status	Zie bijlage B voor lijst met geadviseerde statussen voor aangesloten basisregistraties.(Het is toegestaan om in de eigen catalogus afwijkende statussen op te nemen)	[0..1]
Annotatiestatus.Statustype		[0..1]

Annotatie.Contactinformatie	Contactgegevens.	[0..*]
Contactinformatie.@ContactType	Kan alleen de waarden 'Melder' of 'Behandelaar' hebben.	[1..1]
Contactinformatie.Annotatiebasis
Contactinformatie.Naam		[1..1]
Contactinformatie.Telefoon		[0..1]
Contactinformatie.Email		[1..1]
Contactinformatie.Afdeling		[0..1]

Annotatie.Planningsverwachting	Verwachte termijn voor behandeling.	[0..*]
Planningsverwachting.Annotatiebasis
Planningsverwachting.MijlpaalAanduiding	Beschrijving van de planningsverwachting.	[0..1]
Planningsverwachting.MijlpaalTijdstempel	Datum waarop de planning gereed is.	[0..1]

Annotatie.BehandelendeBronhouder	Behandelende bronhouder	[0 *]
BehandelendeBronhouder.Annotatiebasis
BehandelendeBronhouder.Bronhouder	De gewenste bronhouder (bij status "Verkeerde Bronhouder")	[1..1]

Optioneel kan bij een statuswijziging worden meegezonden:

Planningsverwachting, Contactinformatie en Behandelendbronhouder (hiermee kan bij de statuswijziging "Verkeerde Bronhouder" de gewenste bronhouder worden aangegeven).

Het antwoord op het toevoegen van een annotatie of het nu een annotatieboom met volledige terugmelding is of een annotatie voor een intrekking is altijd een AnnotatieToevoegenResponse-bericht met daarin een tijdstempel. Het is een zogeheten functionele acknowledgement wat betekent dat de achterliggende (TMV-)applicatie het vraagbericht in goede orde ontvangen heeft.

Berichttype: AnnotatieToevoegenResponse
Elementen/attributen
AnnotatieToevoegenResponse
AnnotatieToevoegenResponse . Tijdstempel	Tijd waarop antwoord verstuurd is.	[1..1]
AnnotatieToevoegenResponse . AnnotatieVerwijzing	UUID van de toegevoegde annotatie waar het antwoord betrekking op heeft.	[1..1]

Deze interactie wordt gebruikt door de afnemer om meer informatie te verkrijgen over de door zijn organisatie gedane terugmeldingen en de huidige status van deze terugmeldingen.


Doel	Het opvragen van de status van terugmeldingen van een terugmeldende organisatie.
Voorwaarde	De organisatie heeft terugmeldingen gedaan.
Trigger	Een gebruiker wil de status van terugmeldingen van zijn organisatie weten.
Direct gevolg	De gebruiker is geïnformeerd over de status en eventueel extra detailinformatie van de terugmeldingen die hem interesseren.
Vervolgactie	De gebruiker kan terugmeldingen van zijn organisatie intrekken op basis van de informatie verstrekt in het status overzicht.
Bijzonderheden	-

Het bericht StatusoverzichtRequest wordt gebruikt in de communicatie tussen Afnemer en LV/Basisregistratie alsook tussen LV/Basisregistratie en Bronhouder om een statusoverzicht op te vragen.

Ter illustratie onderstaand de interactie tussen Afnemer en Basisregistratie.

Figuur 6 Interactiediagram status opvragen via de Digimelding Webservice

Figuur 7 Interactiediagram status opvragen rechtstreeks

Het statusoverzicht wordt opgevraagd op basis van de verplichte elementen OIN en basisregistratie. Het OIN is verplicht omdat alle aangesloten basisregistraties alleen van plan zijn terugmeldingen van de afnemer zelf terug te geven. Basisregistratie is verplicht, omdat dit het doorgeven van functionele fouten door de Digimelding Webservice vergemakkelijkt. Dit is een beperkte voorziening, het samenvoegen van overzichtsberichten zou de complexiteit verhogen en vooral op een goede wijze functionele fouten over meerdere basisregistraties heen geven, levert teveel complexiteit op. In het geval dat het opgeven van één basisregistratie verplicht is routeert de Digimelding Webservice slechts. Naast deze verplichte elementen is er een aantal optionele elementen waarmee de resultaten gefilterd kunnen worden. Een lijst met kenmerken van de organisatie zelf kan worden meegegeven. Dit is handig wanneer de afnemer een eigen registratiesysteem heeft. Daarnaast kan gefilterd worden op de datum van indienen en de datum van laatste wijziging. Tot slot kan er gefilterd worden op de status van terugmeldingen. Dit is enigszins bewerkelijk aangezien iedere basisregistratie zijn eigen statussen mag definiëren. In de berichtenschema's is daarom slechts vastgelegd dat dit een string is.

Berichttype: StatusoverzichtRequest
Elementen/attributen
OinVragendeOrganisatie	OIN van de vragende organisatie.	[1..1]
OinBasisregistratie	*Het OIN van de houder van een landelijke voorziening van de basisregistratie	[1..1]
Registratie	Code (maximaal 3 letterig) waarmee de basisregistratie wordt aangeduid wanneer de houder van een landelijke voorziening meer dan 1 basisregistratie beheert (bv BRT, BGT).	[0..1]
Filter		[0..1]
Filter.MeldingskenmerkenLijst	(Lijst met)Eigen kenmerk(en) terugmeldende organisatie.	[0..1]
Filter.MeldingskenmerkenLijst.MeldinggkenmerkLijstElement		[1..*]
Filter.VanafTijdstempelIndienen	Filtert resultaten die zijn ingediend voor dit tijdstempel weg. Resultaten op de tijdstempel of daarna worden getoond.	[0..1]
Filter.TotEnMetTijdstempelIndienen	Filtert resultaten die zijn ingediend na dit tijdstempel weg. Resultaten op de tijdstempel of daarvoor worden getoond.	[0..1]
Filter.VanafTijdstempelWijziging	Filtert resultaten die zijn gewijzigd voor dit tijdstempel weg. Resultaten op de tijdstempel of daarna worden getoond⁴.	[0..1]
Filter.TotEnMetTijdstempelWijziging	Filtert resultaten die zijn gewijzigd na dit tijdstempel weg. Resultaten op de tijdstempel of daarvoor worden getoond⁴.	[0..1]
Filter.StatusTerugmelding	String met daarin een status behorende bij de basisregistratie waarvan het overzicht gevraagd wordt.	[0..1]
Filter.Objectidentificatie	String met daarin een objectidentificatie behorende bij de basisregistratie waarvan het overzicht gevraagd wordt. Hiermee kunnen terugmeldingen ook op basis van KvK-nummer, BSN-nummer, BAG-id, etc teruggevonden worden.	[0..1]

Noot

⁴ *Het resultaat* betreft terugmeldingen (annotatiebomen) waarvoor geldt dat **de laatste annotatie** is toegevoegd tussen VanafTijdstempelWijziging en TotEnMetTijdstempelWijziging

Het statusoverzicht geeft een lijst met annotaties terug. Dit zijn in dit geval altijd 'root' annotaties waar een annotatieboom aan hangt. Dit is noodzakelijk omdat een aantal van de kenmerken die in de annotatielijst verplicht worden meegegeven afkomstig zijn uit leaf annotaties van een annotatieboom.

Wanneer het antwoord op een statusoverzichtbevraging niets oplevert wordt een lege lijst meegegeven. In lijn met het 'gemeenschappelijke afspraken berichtstandaarden'-voorstel voor 'geen waarde' wordt hierbij als reden meegegeven 'geenWaarde'. Een regulier antwoordbericht is in deze foutsituaties op zijn plaats omdat dit geen kritieke fouten zijn en het aan de afnemer is om te bepalen of hier actie op moet worden ondernomen.

Berichttype: StatusoverzichtResponse
Elementen/attributen
AnnotatieLijst		[1..*]
Annotatie		[0..*]
Annotatie . Tijdstempel	Datum/tijd waarop de annotatie heeft plaatsgevonden	[1..1]
Annotatie . Uuid	Unieke verwijzing naar de root annotatie van een annotatieboom.	[1..1]
Annotatie . Meldingskenmerk	Eigen kenmerk terugmeldende organisatie.	[1..1]
Annotatie . Bronverwijzing		[1..1]
Annotatie . Bronverwijzing . Uri	Een combinatie van OIN en de unieke sleutel van het brongegeven zodat een unieke referentie ontstaat naar het brongegeven (bijv. OIN en HRN).	[1..1]
Annotatie . Bronverwijzing . Selectie	Object waarop is teruggemeld.	[0..1]
Annotatie . Annotatiestatus	Laatste status annotatie van de terugmelding.	[1..1]

Het bericht DetailsTerugmeldingRequest wordt gebruikt in de communicatie tussen Afnemer en LV/Basisregistratie alsook tussen LV/Basisregistratie en Bronhouder om details van een bepaalde terugmelding op te vragen.

Ter illustratie onderstaand de interactie tussen Afnemer en Basisregistratie.

Figuur 8 Interactiediagram details terugmelding bevragen via Digimelding Webservice

Figuur 9 Interactiediagram detail terugmelding bevragen rechtstreeks

Het doel van dit bericht is het opvragen van alle informatie over één terugmelding bij een basisregistratie. Hiervoor wordt het OIN van de afnemer meegegeven en de basisregistratie waar de detailopvraging wordt gedaan, tot slot wordt de UUID van de annotatie meegegeven. In de huidige praktijk gaat het altijd om een UUID van een root annotatie. Volgens het protocol kan ook een individuele leaf annotatie of een deelboom worden opgevraagd. Dit is nu in theorie mogelijk maar wordt in de praktijk niet toegepast en is niet getest.

Berichttype: DetailsTerugmeldingRequest
Elementen/attributen
OinVragendeOrganisatie	Identificatie d.m.v. OIN-vragende organisatie.	[1..1]
OinBasisregistratie	Het OIN van de houder van een landelijke voorziening van de basisregistratie	[1..1]
Registratie	Code (maximaal 3 letterig) waarmee de basisregistratie wordt aangeduid wanneer de houder van een landelijke voorziening meer dan 1 basisregistratie beheert (bv BRT, BGT).	[0..1]
Uuid	UUID van root annotatie.	[1..1]

Op basis van een UUID geeft een basisregistratie de annotatie met daaraan hangende leafs terug als antwoord. Op dit moment is dat altijd een toevoeging of wijziging (terugmelding) als root annotatie met daaraan altijd tenminste één van elk van de volgende leafs: contact, meldingskenmerk en/of status. Daarnaast worden optioneel één of meerdere leafs van het type: Bijlageverwijzing en Planningsverwachting meegegeven.

Een basisregistratie moet het opvragen van root annotaties met eraan hangende boom ondersteunen, daarnaast mag een basisregistratie annotatie(bomen) teruggeven van niet root annotaties, dit is echter nu nog niet gerealiseerd of getest. Aangezien het statusoverzicht alleen root annotaties oplevert zal het opvragen van andere soorten annotaties in de praktijk ook niet snel voorkomen.

Doordat de annotatiebasis in iedere annotatie zit wordt de annotatieboom een behoorlijk lijvige constructie. In de onderstaande berichten wordt deze daarom tot één regel afgekort. Zie paragraaf 4.1 voor een uitgebreide toelichting van wat er in de annotatiebasis staat. Elke annotatie kent een eigen instantie, zoals ook bij 'AnnotatieToevoegenRequest' en elke annotatie kan slechts één van de volgende soorten annotaties bevatten: Terugmelding, Annotatiestatus, Referentiekenmerk, Contactinformatie, Bijlageverwijzing, Planningsverwachting en BehandelendeBronhouder.

Berichttype: DetailsTerugmeldingResponse
Elementen/attributen
AnnotatieBoom	De container die de verzameling annotaties bevat die ofwel het gevraagde UUID als kenmerk hebben of daar middels een annotatieverwijzing naar verwijzen.	[1..1]
Annotatie.Terugmelding	De terugmelding (de annotatie die uiteindelijk de root annotatie zal worden)	[1..1]
Terugmelding.Annotatiebasis
Terugmelding.Bronverwijzingen	Bronverwijzingen bestaande uit één of meerdere bronverwijzing(en) Lijst van verwijzingen met basisregistratie elementen waarop wordt teruggemeld.	[1..1]
Bronverwijzingen.Bronverwijzing	Bestaande uit een URI en een selectieverwijzing naar het basisregistratie element waarop wordt teruggemeld. Dit mogen er meerdere zijn, maar in de huidige praktijk is dit er altijd precies één.	[1..*]
Bronverwijzing.Uri	De URI die de combinatie van basisregistratie en sleutel (bijvoorbeeld BSN of HRN) uniek identificeert.	[1..1]
Bronverwijzing.Selectie	Selectie van een element binnen de structuur die door de URI uniek geïdentificeerd wordt (bijvoorbeeld onderneming).	[0..*]
Terugmelding.Attributenset	De set van attributen die daadwerkelijk gewijzigd dienen te worden.	[1..1]
Attributenset.Attribuut	Eén of meerdere attributen die gewijzigd dienen te worden.	[1..*]
Attribuut.Uri	De unieke aanduiding van het attribuut	[1..1]
Attribuut.BetwijfeldeWaarde	De bestaande waarde in de basisregistratie.	[0..1]
Attribuut.VoorgesteldeWaarde	De voorgestelde nieuwe waarde.	[0..1]
Terugmelding.Peilmoment	De datum waarop de betwijfelde waarde geldig is en de voorgestelde waarde geldig zou moeten zijn.	[0..1]

Annotatie.Annotatiestatus	Status van de terugmelding, de status met de meest recente datum GeannoteerdOp is de geldige status.	[1..*]
Annotatiestatus.Annotatiebasis
Annotatiestatus.Status	*Zie bijlage B voor lijst met geadviseerde statussen voor aangesloten basisregistraties. Het is toegestaan om in de eigen catalogus afwijkende statussen op te nemen)	[1..1]

Annotatie . Referentiekenmerk	Eigen kenmerk terugmeldende organisatie (het mogen er meer zijn, in de huidige praktijk altijd precies één).	[1 *]
Referentiekenmerk.Annotatiebasis
Referentiekenmerk.Kenmerk	Eigen kenmerk terugmeldende organisatie.	[1..1]

Annotatie.Contactinformatie	Contactgegevens.	[1 *]
Contactinformatie.@ContactType	kan alleen de waarden 'Melder' of 'Behandelaar' hebben	[1..1]
Contactinformatie.Annotatiebasis
Contactinformatie.Naam		[1..1]
Contactinformatie.Telefoon		[0..1]
Contactinformatie.Email		[1..1]
Contactinformatie.Afdeling		[0..1]

Annotatie . Bijlageverwijzing	Metainformatie over bijlagen. Wordt in de praktijk niet ondersteund door BRP, HR ondersteunt er maximaal 5.	[0..*]
Bijlageverwijzing . Annotatiebasis
Bijlageverwijzing . Bestandsnaam	De naam van het bestand.	[1..1]
Bijlageverwijzing . MIMEType	Het MIME type van de bijlage.	[1..1]
Bijlageverwijzing . BijlageData	*Het bestand zelf in Base64-binary encoding.⁵	[1..1]
Bijlageverwijzing . Beschrijving	*Beschrijving van de bijlage. De bijlage zelf wordt nooit mee teruggeleverd bij het bevragen van een terugmelding/annotatie.	[0..1]

Annotatie . Planningsverwachting	Verwachte termijn voor behandeling, wordt alleen gebruikt door BRP en komt dan slechts eenmaal voor.	[0..*]
Planningsverwachting . Annotatiebasis
Planningsverwachting . MijlpaalAanduiding	Beschrijving van de planningsverwachting.	[0..1]
Planningsverwachting . MijlpaalTijdstempel	Datum waarop de planning gereed is.	[0..1]

Annotatie . BehandelendeBronhouder	Behandelende bronhouder, huidige behandelaar is leaf annotatie met meest recente tijdstempel.	[0 *]
BehandelendeBronhouder . Annotatiebasis
BehandelendeBronhouder . Bronhouder	De bronhouder die de terugmelding momenteel in behandeling heeft.	[1..1]

Noot

⁵ Dit veld wordt bij een bericht 'DetailsTerugmeldingResponse' leeg gelaten

De berichten beschreven in deze uitwisseling kunnen worden gebruikt om te controleren of de berichtverwerking in zijn algemeenheid beschikbaar is.


Doel	Het ontvangen van een antwoordbericht waaruit blijkt dat de berichtverwerking conform specificaties werkt.
Voorwaarde	Geen.
Trigger	Behoefte om te controleren of berichtverwerking naar behoren functioneert.
Direct gevolg	Terugsturen van een echobericht.
Vervolgactie	Indien de echo faalt onderzoeken waardoor dit wordt veroorzaakt.
Bijzonderheden

Figuur 11 Interactiediagram echoverzoek via Digimelding Webservice

De structuur van het echoverzoek is als volgt:

Berichttype: EchoRequest
EchoRequest.OinBasisregistratie	Het OIN van de basisregistratie waar het echoverzoek naar toe moet	[1..1]
EchoRequest.OinBasisregistratie	Het OIN van de houder van een landelijke voorziening van de basisregistratie	[1..1]
EchoRequest.Registratie	Code (maximaal 3 letterig) waarmee de basisregistratie wordt aangeduid wanneer de houder van een landelijke voorziening meer dan 1 basisregistratie beheert (bv BRT, BGT).	[0..1]
EchoRequest.Echo	De string die geëchood moet worden	[1..1]

De structuur van het echo-antwoord is als volgt:

Berichttype: EchoResponse
EchoResponse.Echo	De teruggestuurde echo string	[1..1]

Begrip	Toelichting
Doel	Aangeven dat er een fout is opgetreden.
Voorwaarde	Een foutbericht is altijd een reactie op een reeds verzonden bericht, dus één van de vraagberichten uit de voorgaande secties (AnnotatieToevoegenRequest, StatusoverzichtRequest, DetailsTerugmeldingRequest).
Trigger	Het verzonden vraagbericht leidt tot een fout in de verwerking ervan.
Direct gevolg	Een foutbericht wordt verstuurd.
Vervolgactie	De ontvanger van het foutbericht dient de fout af te handelen.
Bijzonderheden

Een aantal foutsituaties is voorstelbaar. Er kan een probleem zijn met autorisatie, met de syntax van de gegevens of er kan een fout optreden in het systeem dat de annotatie moet verwerken.

Wanneer een systeem van de afnemer op transportniveau of applicatieniveau niet geautoriseerd is bij het leverende systeem dan krijgt deze een Digikoppeling-foutmelding 'niet geautoriseerd' terug.

Optioneel kan de basisregistratie in de SOAP Fault-detail meer informatie verstrekken.
Indien een basisregistratie een eigen specifiekere foutcode heeft dan mag deze ook verzonden worden in plaats van de Digikoppeling-melding.

In het geval dat een verwerkingsfout er toe leidt dat een antwoord volledig uitblijft, bijvoorbeeld door het offline zijn van het verwerkende systeem, dan zal de Digikoppeling-adapter van de afnemer een time-out geven.

Indien het bevraagde systeem het bericht niet kan verwerken door een systeemfout maar nog wel kan antwoorden, dan krijgt de afnemer een SOAP Fault-bericht terug met de Digikoppeling-fout DK0051 (time-out), optioneel kan de basisregistratie in de SOAP Fault-detail meer informatie verstrekken. Wanneer het bericht niet verwerkt kan worden vanwege een probleem met de inhoud van het bericht, anders dan de syntax, dan wordt een DK0050-bericht ('kan bericht niet verwerken') verstuurd. Indien een basisregistratie een eigen specifieke foutcode heeft dan mag deze in plaats van de Digikoppeling-foutmelding verstuurd worden.

Indien er een syntaxfout zit in de Digikoppeling-headers, dan volgt hierop een SOAP Fault met de juiste foutcode volgens de Digikoppelingstandaard (er bestaan specifieke foutcodes voor fouten in headervelden).

Indien de inhoud van het vraagbericht niet voldoet aan de syntax van het vraagbericht-XSD of een andere XSD die over de inhoud van het bericht gaat dan wordt een SOAP Fault verstuurd; deze heeft als code DK0004 ('element niet conform XSD'). In de SOAP Fault-detail wordt door de basisregistratie aangegeven tegen welke XSD het bericht niet valideerde. Optioneel is de basisregistratie vrij om nog meer informatie mee te geven in de toelichting. Indien een basisregistratie een eigen specifieke foutcode heeft dan mag deze in plaats van de Digikoppeling-foutcode verstuurd worden.

Synchrone fouten voor Digikoppeling-WUS-berichten worden verstuurd als SOAP Fault zoals dit is voorgesteld voor de berichtenstandaard van het stelsel.⁶ SOAP Faults worden doorgaans door de Digikoppeling-adapter doorgestuurd naar de achterliggende applicatie. Dit koppelvlak gaat er vanuit dat dit ook gebeurt voor de fouten die hier beschreven worden. De foutafhandeling dient in de terugmeldapplicatie plaats te vinden. Binnen de SOAP Fault wordt een aantal velden onderkend te weten:

Noot

⁶ Zie voorstel ["foutafhandeling synchrone berichten" van de "gemeenschappelijke afspraken berichtstandaarden"](https://digistandaarden.pleio.nl/groups/profile/24027452/gemeenschappelijke-afspraken-berichtstandaarden-gab)


Berichttype: DigimeldingSynchroonFault	Synchrone foutafhandeling gaat middels een SOAP Fault
faultcode	De plek waar de fout is opgetreden, één string opgebouwd uit de elementen <Defaultwaarde>.<Code>.<OmschrijvingKort> :	[1..1]
	Defaultwaarde: Bevat één van de defaultwaarden VersionMismatch, MustUnderstand, Client en Server.⁷ Voor Digimeldingpraktijk zijn alleen Client- of Server-waarden relevant om aan te geven wat de aard van de fout is.
	Code: De specifieke foutcode die hoort bij de technische fout (format: <afkortingbron><codering van fout>.

	OmschrijvingKort: De korte omschrijving van de fout (bijvoorbeeld: de Digikoppeling omschrijving uit de lijst met foutmeldingen.* Zie onderstaand voorbeeld.
faultstring	De eigen meer gedetailleerde beschrijving van de foutsituatie. De eigen beschrijving zoveel mogelijk geschikt maken voor het kunnen presenteren aan gebruiker. De ontvanger is niet verplicht deze tekst over te nemen.	[1..1]
faultactor	Bevat een URI van de antwoordende service. Vul de faultactor in met de URI van de bron van de oorzaak, indien het SOAP-bericht langs een tussenstation gaat. Bijvoorbeeld Digimelding Webservice.	[0..*]
faultdetail	Volledig vrij veld om nadere toelichting op de fout te geven, kan gebruikt worden om bijv. achterliggende applicatiefoutmeldingen mee te geven (xs:any).	[0..*]

Noot

⁷ Zie sectie 4.4.1 voor uitleg

Voorbeeld:

Voorbeeld 1: Foutcode


\
  \*soap:Server*\
  \*Fout*\
  \
    **\"\>
    \*001*\
    \*Foutmelding*\
    \*Actor*\
    \
    **\**
  \
\

Voor fouten op protocolniveau dienen de fouten van Digikoppeling gevolgd te worden. Voor generieke fouten in Digimelding zijn de volgende Digikoppeling-foutcodes van toepassing:

Nr	Omschrijving	Toelichting
DK0002	Requester systeem niet geautoriseerd	Indien je voor een basisregistratie niet geautoriseerd bent, ontvang je geen inhoudelijke informatie van die basisregistratie. Het autorisatiemodel wordt door de basisregistratie bepaald. In de foutmelding wordt de betreffende basisregistratie, waarvoor geen autorisatie bestaat, teruggegeven.
DK0004	Element niet conform XSD	Bij een validatiefout wordt meegegeven in het SOAP Faultdetail aan welke XSD niet voldaan wordt.
DK0050	Proces voor afhandelen bericht geeft fout	Wanneer een bericht zich niet houdt aan afspraken die gemaakt zijn rondom de vulling van de payload welke basisregistratiespecifiek zijn, bijvoorbeeld: Status is volgens de XSD een vrij tekstveld, iedere basisregistratie is vrij deze te kiezen. De basisregistratie kan teruggeven dat een status bij hen niet bekend is.
DK0051	Antwoordend systeem geeft time-out	Indien de achterliggende applicatie niet draait of een fout produceert dan kan het geen antwoord geven terwijl een geldig antwoord wel mogelijk zou moeten zijn en de messaging stack(Digikoppeling) nog wel in de lucht is.

Afkorting	Omschrijving
BAG	Basisregistratie Adressen en Gebouwen
BRP	Basisregistratie Personen
GEMMA	Gemeentelijke modelarchitectuur
ICTU	ICT Uitvoeringsorganisatie
KING	Kwaliteitsinstituut Nederlandse Gemeenten
HR	Handelsregister
NUP	Nationaal Uitvoeringsprogramma
StUF	Standaarduitwisselingsformaat

Digimelding-koppelvlakspecificatie

Handreiking

Logius Handreiking Versie ter vaststelling 01 juni 2021

Status van dit document

1. Conformiteit

Documentbeheer

Colofon

2. Inleiding

2.1 Achtergrond

2.2 Bronverwijzing en referentiedocumenten

3. Functionaliteit op hoofdlijnen en architectuur

3.1 Referentiearchitectuur

4. Beveiliging, autorisatie en protocollen

4.1 Authenticatie en autorisatie

4.1.1 Protocollen

5. Specificaties Services

5.1 Annotaties Algemeen

5.2 Annotatie versturen

5.2.1 Algemeen

5.2.2 Scenario's Communicatie

5.2.3 Inhoud bericht Annotatie ToevoegenRequest

5.2.3.1 Annotatie toevoegen (terugmelden)

5.2.3.2 Annotatie toevoegen (intrekken)

5.2.3.3 Annotatie toevoegen (aanpassing)

5.3 Status bevragen

5.3.1 Algemeen

5.3.2 StatusoverzichtRequest

5.3.3 StatusoverzichtResponse

5.3.4 DetailsTerugmeldingRequest

5.3.5 DetailsTerugmeldingResponse

5.4 Echo

5.4.1 Algemeen

5.4.2 EchoRequest

5.4.3 EchoResponse

6. Foutberichten

6.1 Autorisatiefouten

6.2 Verwerkingsfouten

6.3 Syntaxfouten

6.4 Generieke foutcodes van toepassing op Digimelding

7. bijlagen

7.1 Bijlage A: Afkortingen, begrippen en symbolen

7.2 Bijlage B : Geadviseerde Statussen

Logius Handreiking
Versie ter vaststelling 01 juni 2021