Hoofdinhoud
Inleiding
Deze pagina geeft inzicht in de machine-to-machine-koppelingen die Digilevering biedt:
- verstrekken van een gebeurtenis door Landelijke Voorziening aan Digilevering
- verstrekken van een gebeurtenis door Digilevering aan een afnemer
- aanpassen van een objectverzameling door de afnemer
NB
Digilevering kent ook een uitbreiding voor wat betreft de BRP-connector. Het aansluiten op Digilevering als ook de werking van Digilevering m.b.t. deze Basisregistratie (HLV) verschilt echter wezenlijk van hetgeen op deze pagina is beschreven. Daarom is er bewust voor gekozen om het koppelvlak en de werking van de zogenaamde “Digilevering BRP-connector” in een separaat document te beschrijven. Dit om onnodige verwarring te voorkomen. Zeker voor partijen welke niets met deze Basis Register van doen hebben.
Overzicht
Overzicht services
Digilevering definieert vier services, waarvan er twee door Digilevering zelf worden geïmplementeerd en twee door de afnemers moeten worden geïmplementeerd:
- verwerk gebeurtenis
- ontvang gebeurtenis (te implementeren door de afnemer)
- mutatie objecten (te implementeren door de afnemer)
- beheer objectverzameling
De webservices verwerk gebeurtenis en ontvang gebeurtenis zijn sterk aan elkaar verwant: een verstrekking door LV (van een gebeurtenis voor verwerk gebeurtenis) leidt tot een aantal verstrekkingen aan afnemer, zoals weergegeven in het diagram op de volgende pagina.
Deze services zullen in de volgende hoofdstukken worden behandeld. Daarna volgen de functionele berichtspecificaties, gevolgd door de XML-schema’s en een aantal bijzonderheden. Als laatste zijn er ook voorbeeldberichten opgenomen.
Digikoppeling - ebMS
Alle machine-to-machine koppelingen maken gebruik van ebMS conform de Digikoppeling standaard.
XML-elementen en XML-attributen
In Digilevering worden vrijwel alleen XML-elementen gebruikt. Dit is in het bijzonder van belang voor de gebeurtenisinhoud en de inhoud van de Afnemersberichten. Elk gegevenselement wordt afgebeeld op een XML-element. Digilevering biedt ook ondersteuning voor XML-attributen in de gebeurtenisinhoud en de Afnemersberichten; deze worden doorgegeven zoals ze binnenkomen. In de objectidentificatie inhoud worden geen XML-attributen ondersteund.
Een verstrekking door LV (van een gebeurtenis) leidt tot nul, één of meer verstrekkingen aan afnemers
Services voor gebruik door Landelijke Voorziening
Overzicht
In onderstaande tabel wordt een overzicht van de services voor een Landelijke Voorziening gegeven. Deze wordt hierna behandeld
| Provider | ebMS-Service | Action/Element | Requester | |
|---|---|---|---|---|
| 1 | Digilevering | dgl:verstrekken | dgl:verstrekkingDoorLV | Landelijke Voorziening |
3.2. Service verwerk gebeurtenis /dgl:verstrekken
Landelijke Voorziening stuurt gebeurtenissen (verstrekkingen) aan Digilevering. Digilevering bepaalt vervolgens op basis van de geldende abonnementen aan welke afnemers deze gebeurtenis moet worden verstrekt, waarbij alleen gegevens worden doorgegeven zoals in het abonnement vastgelegd.
| ebMS-service: | dgl:verstrekken |
|---|---|
| ebMS-action: | verwerken |
| Bericht-naam: | dgl:verstrekkingDoorLV |
Zie DGL BT-1: Gebeurtenis landelijke voorziening voor de berichtspecificatie.
Zie digilevering.xsd voor het XML-schema.
Services voor gebruik door afnemers
Overzicht
In onderstaande tabel wordt een overzicht gegeven van de services voor de afnemers. Deze worden hierna behandeld.
| Provider | ebMS-Service | Action/Element | Requestor | |
|---|---|---|---|---|
| 1 | Digilevering | dgl:ontvangen | dgl:verstrekkingAanAfnemer | Afnemer |
| 2 | Afnemer | dgl:objecten | dgl:mutatieObjecten | Digilevering |
Service ontvang gebeurtenis /dgl:ontvangen
Digilevering stuurt een gebeurtenis (verstrekking) aan een afnemer. De afnemer implementeert daarvoor deze service die de verstrekking ontvangt en vervolgens verwerkt. De aard van de verwerking is volledig aan de afnemer.
| ebMS-service: | dgl:ontvangen |
|---|---|
| ebMS-action: | verstrekkingAanAfnemer |
| Bericht-naam: | dgl:verstrekkingAanAfnemer |
Zie DGL BT-2: Gebeurtenis afnemer voor de berichtspecificatie.
Zie digilevering.xsd voor het XML-schema
Service beheer objecten /dgl:objecten
Afnemers kunnen objecten toevoegen aan en verwijderen uit de bij een abonnement behorende objectverzameling om daarmee hun interesse in gebeurtenissen betreffende die objecten aan te geven.
| ebMS-service: | dgl:objecten |
|---|---|
| ebMS-action: | mutatieObjecten |
| Bericht-naam: | dgl:mutatieObjecten |
Zie DGL BT-3: Objectidentificatie voor de berichtspecificatie.
Zie digilevering.xsd voor het XML-schema.
Controlebericht Ping/ antwoordbericht Pong
Het is mogelijk om te testen of een ebMS service beschikbaar is door een Ping-bericht te versturen. Zie DGL BT-4: controlebericht Ping voor de berichtspecificatie van een Ping-bericht. Als de ebMS service dan beschikbaar is, zal een Pong-bericht worden teruggestuurd. Zie DGL BT-5: antwoordbericht Pong voor de berichtspecificatie van een Pong-bericht. Zie digilevering.xsd voor het XML-schema van zowel het Ping- als het Pong-bericht.
In de volgende paragrafen wordt de Ping Pong functionaliteit per ebMS service toegelicht.
Verstrekken
In onderstaande afbeelding wordt een overzicht van de Ping Pong services op de ebMS service 'dgl:verstrekken' gegeven:
Het Ping-bericht wordt verstuurd door Landelijke Voorziening en ontvangen door Digilevering. Indien de ebMS service 'dgl:verstrekken' beschikbaar is, stuurt Digilevering een Pong-bericht terug.
Ontvangen
In onderstaande afbeelding wordt een overzicht van de Ping Pong services op de ebMS service 'dgl:ontvangen' gegeven:
Het Ping-bericht wordt verstuurd door Digilevering en ontvangen door het Afnemer systeem. Indien de ebMS service 'dgl:ontvangen' beschikbaar is, stuurt het Afnemer systeem een Pong-bericht terug.
Objecten
In onderstaande afbeelding wordt een overzicht van de Ping Pong services op de ebMS service 'dgl:objecten' gegeven:
Het Ping-bericht kan worden verstuurd door een Afnemer systeem en wordt ontvangen door Digilevering. Indien de ebMS service 'dgl:objecten' beschikbaar is, stuurt Digilevering een Pong-bericht terug.
Digilevering Bericht Types (DGL BT)
DGL BT-1: Gebeurtenis landelijke voorziening
| Berichttypenummer | Digilevering BT-1 |
|---|---|
| Berichttypenaam | Gebeurtenis landelijke voorziening - dgl:verstrekkingDoorLV< |
| Van | Landelijke voorziening |
| Naar | Digilevering |
| Functie | Met dit berichttype kan Landelijke Voorziening een gebeurtenis verstrekken aan Digilevering, zodat deze het bericht kan verstrekken aan de geabonneerde afnemers. |
| Gebruikt in webservice | WS-1: Verstrekken gebeurtenis |
| Standaard | ebMS volgens OSB 2.0 |
| Element | Betekenis |
|---|---|
| Datumtijdstempel LV | Door Landelijke Voorziening aangebrachte datum + tijdstip waarop de gebeurtenis is verstuurd. |
| Kenmerk LV | Door Landelijke Voorziening aangebracht kenmerk van het gebeurtenisbericht. |
| ReferentieId | Hier kan het oorspronkelijke message-ID van de Afnemer, dat wordt vermeld door de RvIG, worden meegegeven (Veld is optioneel) |
| Versie berichttype | Aanduiding van de versie van het berichttype (versie van de berichtdefinitie waarop het bericht is gedefinieerd). |
| Basisregistratie | Aanduiding van de basisregistratie waarvan de gebeurtenis afkomstig is. |
| Gebeurtenissoort | Aanduiding van de gebeurtenissoort (naam en versie) waarop de gebeurtenis betrekking heeft. |
| Filterinhoud | Specificatie van de inhoud waarop berichten in Digilevering gefilterd kunnen worden. De filterinhoud bestaat uit minimaal 0 en maximaal 8* verschillende filterelementen (filter1, filter2 t/m filter8). Een bepaald filterelement mag meerdere keren voorkomen. Dus bv 3x filter3 met verschillende inhoud. Ook is de volgorde van de verschillende filterelementen niet vast: dus bv eerst filter5, dan filter2, dan filter8 en dan weer filter2, etc. Indien een filterelement een datum/tijd bevat, wordt hierop geen tijdzone conversie uitgevoerd. |
| Gebeurtenisinhoud | Specificatie van de inhoud van de gebeurtenis. Inhoud is afhankelijk van de gebeurtenissoort. De inhoud kan, maar hoeft geen, StuF compliant bericht te zijn. |
Binnen Digilevering zal het maximumaantal verschillende filterelementen configureerbaar zijn, in de bericht specificatie is dit op 8 gemaximeerd.
Voor een voorbeeld van dit bericht, alsmede voorbeelden van hoe data van een bepaald domein in de filterinhoud moet worden aangeleverd, wordt verwezen naar Voorbeelden van berichten.
DGL BT-2: Gebeurtenis afnemer
| Berichttypenummer | Digilevering BT-2 |
|---|---|
| Berichttypenaam | Gebeurtenis afnemer - dgl:verstrekkingAanAfnemer |
| Van | Digilevering |
| Naar | Afnemer |
| Functie | Met dit berichttype kan Digilevering een gebeurtenis verstrekken aan de afnemer. |
| Gebruikt in webservice | WS-2: Ontvang gebeurtenis |
| Standaard | ebMS volgens OSB 2.0 |
| Element | Betekenis |
|---|---|
| Datumtijdstempel Digilevering | Door Digilevering aangebrachte datum + tijdstip waarop de gebeurtenis is verstuurd. |
| Datumtijdstempel LV | Door Landelijke Voorziening aangebrachte datum+ tijdstip waarop de gebeurtenis (oorspronkelijk) is verstuurd aan Digilevering. |
| Kenmerk Digilevering | Door Digilevering aangebracht kenmerk van het gebeurtenisbericht. |
| Kenmerk LV | Door Landelijke Voorziening aangebracht kenmerk van het oorspronkelijke gebeurtenisbericht. |
| ReferentieId | Hier kan het oorspronkelijke message-ID van de Afnemer, dat wordt vermeld door de RvIG, worden meegegeven (Veld is optioneel) |
| Versie berichttype | Aanduiding van de versie van het berichttype (versie van de berichtdefinitie waarop het bericht is gedefinieerd). |
| Abonnement | Aanduiding van het abonnement op basis waarvan de gebeurtenis wordt verstrekt. |
| Basisregistratie | Aanduiding van de basisregistratie waarvan de gebeurtenis afkomstig is. |
| Gebeurtenissoort | Aanduiding van de gebeurtenissoort (naam en versie) waarop de gebeurtenis betrekking heeft. |
| Gebeurtenisinhoud | Specificatie van de inhoud van de gebeurtenis. Inhoud is afhankelijk van de gebeurtenissoort en de toegepaste autorisatieregels. |
Merk op dat Filterinhoud en de Filterelementen uit de BT-1 Gebeurtenis Landelijke Voorziening niet terugkomen in de BT-2 Gebeurtenis afnemer.
Voor een voorbeeld van dit bericht, wordt verwezen naar Voorbeelden van berichten.
DGL BT-3: Objectidentificatie
| Berichttypenummer | Digilevering BT-3 |
|---|---|
| Berichttypenaam | Objectidentificatie - dgl:mutatieObjecten |
| Van | Afnemer |
| Naar | Digilevering |
| Functie | Met dit berichttype kan de afnemer mutaties op de bij een abonnement behorende objectlijst doorgeven, zodat Digilevering de objectlijst kan bijwerken. |
| Gebruikt in webservice | WS-3: Beheren objectlijst |
| Standaard | ebMS volgens OSB 2.0 |
| Element | Betekenis |
|---|---|
| Datumtijdstempel afzender | Door de afnemer aangebrachte datum + tijdstip waarop de objectidentificaties zijn verstuurd. |
| Kenmerk afnemer | Door de afnemer aangebracht kenmerk van het bericht. |
| Versie berichttype | Aanduiding van de versie van het berichttype (versie van de berichtdefinitie waarop het bericht is gedefinieerd). |
| Abonnement | Aanduiding van het abonnement waarop de objectlijst betrekking heeft. |
| Gewenste mutatie | Aanduiding van de gewenste mutatiesoort (toevoeging of verwijdering). Dit bepaalt de door Digilevering uit te voeren actie. |
| Objectidentificatie(s) | Eén of meer objectidentificaties (inclusief typering). |
Voor een voorbeeld van dit bericht, wordt verwezen naar Voorbeelden van berichten.
DGL BT-4: controlebericht Ping
| Berichttypenummer | Digilevering BT-4 |
|---|---|
| Berichttypenaam | Ping |
| Van | Digilevering/Afnemer/Landelijke Voorziening |
| Naar | Digilevering/Afnemer/Landelijke Voorziening |
| Functie | Controleren of een berichten tussen twee partijen kunnen worden uitgewisseld |
| Gebruikt in webservice | WS-1: Verstrekken gebeurtenis WS-2: Ontvang gebeurtenis WS-3: Beheren objectlijst |
| Standaard | ebMS volgens OSB 2.0 |
| Element | Betekenis |
|---|---|
| Kenmerk | Door afzender gekozen uniek kenmerk voor dit bericht |
| Datumtijdstempel | Door de afzender aangebrachte datum+ tijdstip waarop het bericht is verstuurd door de afzender |
Voor een voorbeeld van dit bericht, wordt verwezen naar Voorbeelden van berichten.
DGL BT-5: antwoordbericht Pong
| Berichttypenummer | Digilevering BT-5 |
|---|---|
| Berichttypenaam | Pong |
| Van | Digilevering/Afnemer/Landelijke Voorziening |
| Naar | Digilevering/Afnemer/Landelijke Voorziening |
| Functie | Antwoordbericht op controlebericht ping |
| Gebruikt in webservice | WS-1: Verstrekken gebeurtenis WS-2: Ontvang gebeurtenis WS-3: Beheren objectlijst |
| Standaard | ebMS volgens OSB 2.0 |
| Element | Betekenis |
|---|---|
| Kenmerk ping | Door de afzender ping gekozen uniek kenmerk voor dit bericht |
| Datumtijdstempel ping | Door de afzender ping aangebrachte datum+ tijdstip waarop het bericht is verstuurd door de afzender |
| Kenmerk pong | Door de beantwoorder pong gekozen uniek kenmerk voor dit bericht |
| Datumtijdstempel pong | Door de beantwoorder pong aangebrachte datum+ tijdstip waarop het bericht is verstuurd door de afzender |
Voor een voorbeeld van dit bericht, wordt verwezen naar Voorbeelden van berichten.