Merge pull request #7 from Logius-standaarden/review

Review is gereviewed. Door naar develop.
Logius-standaarden · Jun 8, 2023 · 2f819cd · 2f819cd
2 parents dce9cdf + b8ac556
commit 2f819cd
Show file tree

Hide file tree

Showing 7 changed files with 146 additions and 134 deletions.
diff --git a/02_documentbeheer.md b/02_documentbeheer.md
@@ -1,10 +1,11 @@
 # Documentbeheer
 
-| Datum      | Versie | Auteur | Opmerkingen |
-|------------|--------|--------|-------------|
-| 22-11-2011 | 1.5    | Logius | - |
-| 09-06-2014 | 1.6    | Logius | Redactioneel bijwerken |
-| 13-01-2015 | 3.0    | Logius | Redactioneel  |
+| Datum      | Versie | Auteur | Opmerkingen                                                                 |
+|------------|--------|--------|-----------------------------------------------------------------------------|
+| 22-11-2011 | 1.5    | Logius | -                                                                           |
+| 09-06-2014 | 1.6    | Logius | Redactioneel bijwerken                                                      |
+| 13-01-2015 | 3.0    | Logius | Redactioneel                                                                |
 | 01-10-2017 | 3.1    | Logius | Herzien nav:  - Compliance Voorziening  - Begrippen ebMS2 en CPA   Register |
-| 16-05-2019 | 3.2    | Logius | EB015 SyncReply toegevoegd  |
-| 11/04/2022 | 3.2.1  | Logius | Vermelding REST-API koppelvlak  |
+| 16-05-2019 | 3.2    | Logius | EB015 SyncReply toegevoegd                                                  |
+| 11-04-2022 | 3.2.1  | Logius | Vermelding REST-API koppelvlak                                              |
+| 31-05-2023 | 3.2.2  | Logius | Update 2023 conform Roadmap Digikoppeling, review |
diff --git a/03_colofon.md b/03_colofon.md
@@ -3,3 +3,4 @@
 | | |
 |---|---|
 | Logius Servicecentrum: | Postbus 96810 <br>2509 JE Den Haag<br>tel. 0900 555 4555 (10 ct p/m)<br>email servicecentrum@logius.nl |
+| Logius Afdeling Standaarden: | email. digikoppeling@logius.nl<br>                                                              |
diff --git a/ch01_Inleiding.md b/ch01_Inleiding.md
@@ -1,4 +1,5 @@
 # Inleiding
+
 ## Doel en doelgroep
 
 Alle Digikoppeling profielen die op ebMS2 gebaseerd zijn, moeten zich conformeren aan de Koppelvlakstandaard ebMS2. Dit document is een aanvulling hierop. Het heeft als doel ontwikkelaars te adviseren en te informeren over de huidige werkwijze bij het toepassen van Digikoppeling Koppelvlakstandaard ebMS2 – deze informatie geldt dus alleen voor de ebMS2-variant.
@@ -16,10 +17,8 @@ Het document is bestemd voor Architecten, integratie specialisten en ontwikkelaa
 
 Digikoppeling is beschreven in een set van documenten. Deze set is als volgt opgebouwd:
 
-
 ![Overzicht van de onderdelen van de Digikoppeling Standaard, de standaard is onderverdeeld in normatieve en ondersteunende onderdelen](media/DK_Specificatie_structuur.svg "Opbouw documentatie Digikoppeling")
 
-
 <details>
     <summary> Tekstalternatief </summary>
 <ul>
@@ -86,26 +85,27 @@ Digikoppeling biedt de mogelijkheid om op deze gestandaardiseerde wijze berichte
 
 De uitwisseling tussen partijen is in drie lagen opgedeeld:
 
-- Inhoud (gegevens): deze laag bevat afspraken over de inhoud van het uit te wisselen bericht, dus de structuur, semantiek en waardebereiken   
-    Digikoppeling houdt zich niet met de inhoud bezig, ' heeft geen boodschap aan de boodschap'.
+1. Inhoud (gegevens): deze laag bevat afspraken over de inhoud van het uit te wisselen bericht, dus de structuur, semantiek en waardebereiken <BR>
+Digikoppeling houdt zich niet met de inhoud bezig, '_heeft geen boodschap aan de boodschap_'.
 
-- Logistiek (processen): op deze laag bevinden zich de afspraken betreffende transportprotocollen (HTTP/TLS), messaging (SOAP), adressering, beveiliging (authenticatie en encryptie) en betrouwbaarheid. Dit is laag van Digikoppeling.
+2. Logistiek (processen): op deze laag bevinden zich de afspraken betreffende transportprotocollen (HTTP/TLS), messaging (SOAP), adressering, beveiliging (authenticatie en encryptie) en betrouwbaarheid. Dit is laag van Digikoppeling.
 
-- Transport (techniek): deze laag verzorgt het daadwerkelijke transport van het bericht (TCP/IP).
+3. Transport (techniek): deze laag verzorgt het daadwerkelijke transport van het bericht (TCP/IP).
 
-Digikoppeling richt zich uitsluitend op de logistieke laag.
+> Digikoppeling richt zich uitsluitend op de logistieke laag.
 
 ## Opbouw van dit document
 
-Hoofdstuk 1 bevat een aantal algemene inleidende onderwerpen.
-
-Hoofdstuk 2 bevat de aanbevelingen, werkwijze en best practices.
+[Hoofdstuk 1 bevat een aantal algemene inleidende onderwerpen.](#inleiding)
 
-Hoofdstuk 3 gaat in op de kenmerken van een CPA.
+[Hoofdstuk 2 bevat de aanbevelingen, werkwijze en best practices.](#werkwijze-aanbevelingen-best-practices)
 
-Hoofdstuk 4 gaat over bericht volgordelijkheid.
+[Hoofdstuk 3 gaat in op de kenmerken van een CPA.](#cpa-gebruik-en-kenmerken)
 
-Begrippen en afkortingen worden toegelicht in het document “DigikoppelingArchitectuur”. Deze zit in de Digikoppeling standaard.
+[Hoofdstuk 4 gaat over bericht volgordelijkheid.](#het-gebruik-van-berichtvolgordelijkheid)
 
-Dit document en andere documentatie is beschikbaar op [www.logius.nl/digikoppeling](http://www.logius.nl/digikoppeling).
+> Begrippen en afkortingen worden toegelicht in het document [[Digikoppeling-Architectuur]].  
+> Dit document is onderdeel van de Digikoppeling standaard.
 
+<div class="note">Dit document en alle andere Digikoppeling documentatie is beschikbaar op [de website van Logius](http://www.logius.nl/digikoppeling).
+</div>
diff --git a/ch02_WerkwijzeAanbevelingenBest Practices.md b/ch02_WerkwijzeAanbevelingenBest Practices.md
@@ -2,17 +2,17 @@
 
 ## EB001 ebMS2 Producten
 
-Gebruik een ebMS2 product met aantoonbare ervaring binnen het Digikoppeling domein. Op de website van Logius is een overzicht van Digikoppeling leveranciers te vinden en ook in de marktscan van KING en Logius is een overzicht te vinden van het aanbod van Digikoppeling adapters dat voldoet aan de eisen die KING stelt aan een Digikoppeling Adapter voor de gemeentelijke markt.
+Gebruik een ebMS2 product met aantoonbare ervaring binnen het Digikoppeling domein. Op de [website van Logius is een overzicht van Digikoppeling leveranciers](https://logius.nl/domeinen/gegevensuitwisseling/digikoppeling/ict-leveranciers) te vinden. De [GEMMA softwarecatalogus](https://www.softwarecatalogus.nl/pakketten?zoek=digikoppeling+ebms) van de VNG geeft een overzicht van softwareproducten voor de gemeentelijke markt die de Digikoppeling ebMS koppelvlakspecificatie ondersteunen.
 
 ## EB002 CPA Gebruik
 
 Voor het definiëren van een CPA geldt het volgende advies:
 
 1. Raadpleeg het hoofdstuk 3 'CPA Gebruik en Kenmerken'.
 
-1. Maak gebruik van het online CPA Register<sup>1</sup>, zie document 'Digikoppeling CPA Creatie Handleiding'.
+1. Maak gebruik van het online CPA Register<sup>1</sup>, zie het [CPA Register gebruikershandleiding](https://www.logius.nl/domeinen/gegevensuitwisseling/digikoppeling/documentatie/cpa-register-gebruikershandleiding)
 
-<sup>1</sup>: Het online CPA Register wordt gehost door Justid en is beschikbaar op [https://cparegister.minvenj.nl/logius](https://cparegister.minvenj.nl/logius)
+> <sup>1</sup>. Het online CPA Register wordt gehost door Justid en is beschikbaar op [https://cparegister.minvenj.nl/logius](https://cparegister.minvenj.nl/logius)
 
 ## EB003 Productie- en ontwikkelomgevingen
 
@@ -32,7 +32,7 @@ Voorzie de PartyId van een postfix voor het onderscheid tussen test- en producti
 
 Samenstellingen zijn ook mogelijk, bijvoorbeeld de postfix ‘_OTA’ als er één specifiek adres gebruikt wordt voor de ontwikkel-, test-, en acceptatieomgeving. Aangezien Digikoppeling een strikte scheiding tussen test en productie nastreeft zou een combinatie van productie met andere omgevingen nooit moeten voorkomen<sup>2</sup>.
 
-<sup>2</sup>: De scheiding komt ook. tot uitdrukking in het gebruik van een andere certificaat-root voor productie en andere omgevingen. Zie hiervoor het document “Gebruik en achtergrond Digikoppeling-certificaten”.
+> <sup>2</sup>. De scheiding komt ook. tot uitdrukking in het gebruik van een andere certificaat-root voor productie en andere omgevingen. Zie hiervoor het document “Gebruik en achtergrond Digikoppeling-certificaten”.
 
 ## EB005 Certificaten
 
@@ -116,6 +116,8 @@ Laat de start- en einddatum van de CPA mede afhangen van de geldigheid van de ge
 
 Een CPA voor testdoeleinden kan een korte geldigheidsperiode krijgen, afgestemd op de test periode.
 
+Een geldigheidsperiode langer dan 10 jaar is niet gebruikelijk.
+
 ## EB011 MessageOrder en ConversationId
 
 Als de MessageOrder functionaliteit gebruikt wordt, moeten alle betreffende (samenhangende) berichten dezelfde ConversationId krijgen.
@@ -128,7 +130,7 @@ Als MessageOrder gebruikt wordt is dit van invloed op de overdrachtskarakteristi
 
 ## EB013 MessageId
 
-De Koppelvlakstandaard ebMS2 schrijft het gebruik van een MessageId voor conform RFC2822, in de vorm van “[UUID@URI](mailto:UUID@URI)”.
+De Koppelvlakstandaard ebMS2 schrijft het gebruik van een MessageId voor conform [[RFC2822]], in de vorm van “[UUID@URI](mailto:UUID@URI)”.
 
 De URI in de MessageId kan ook het domein kan zijn van Digikoppeling messagehandler.
 
@@ -142,41 +144,43 @@ Het is toegestaan om op transport niveau het cliënt certificaat te gebruiken vo
 
 Het Digikoppeling ebMS2 Reliable Messaging (RM) profiel vereist dat berichten bevestigd worden met een *acknowledgement* bericht. Binnen het Digikoppeling ebMS2 RM-profiel moet deze acknowledgement *asynchroon* worden verzonden. Een Digikoppeling oplossing houdt hiervoor een administratie bij zodat de acknowledgement aan het initiële *MessageId* van het bericht kan worden kan worden gerefereerd
 
-Bij het gebruik van het uitwisselen van zeer hoge volumes van berichten in beperkte tijd via het Digikoppeling ebMS RM-profiel *kan* de overhead van het asynchroon bevestigen van het bericht via asynchrone acknowledgement (te) groot worden. Vandaar dat sinds versie 3.3 van dit profiel het gebruik van SyncReply Profile in de Digikoppeling ebMS2 Specificatie wordt toegestaan voor een aantal uitzonderingsgevallen. Vanaf deze versie is het in bepaalde gevallen mogelijk om een bericht synchroon – dus in dezelfde http-sessie- te bevestigen met een acknowledgement (of een foutsituatie synchroon te beantwoorden met een *errormessage*)
+Bij het gebruik van het uitwisselen van zeer hoge volumes van berichten in beperkte tijd via het Digikoppeling ebMS RM-profiel *kan* de overhead van het asynchroon bevestigen van het bericht via asynchrone acknowledgement (te) groot worden. Vandaar dat sinds versie 3.3 van dit profiel het gebruik van SyncReply Profile in de Digikoppeling ebMS2 specificatie wordt toegestaan voor een aantal uitzonderingsgevallen. Vanaf deze versie is het in bepaalde gevallen mogelijk om een bericht synchroon – dus in dezelfde http-sessie- te bevestigen met een acknowledgement (of een foutsituatie synchroon te beantwoorden met een *errormessage*)
 
 **Toepassen van Synchrone acknowledgement is uitzondering**
 
 Het gebruik van Syncreply wordt in de regel afgeraden. Tot aan versie 3.3 van Digikoppeling ebMS was een invulling van het attribuut SyncReplyMode in het CPA anders dan “none” niet toegestaan, met als onderbouwing: Asynchronous messaging does not preclude fast response times, as is required to support interactive applications. *Asynchronous messaging supports higher levels of scalability and supports scenarios where a response message may be sent minutes, hours or days after the initial request message.* Asynchronous messaging may be combined transparently with store-and-forward intermediaries.
 
 In de praktijk blijkt dat er toch situaties bestaan waarin het synchroon bevestigen van een bericht voordeel biedt:
 
-Casusbeschrijving
+<aside class="example">
+**Casusbeschrijving**
 
 Bij uitwisseling tussen een GDI-voorziening en een grote afnemer worden door de verzendende partij aan de ontvangende partij in korte tijd zeer hoge volumes berichten aangeboden. Vanwege de eis op betrouwbaarheid is voor de uitwisseling gekozen voor het ebMS2 RM-profiel. Deze ebMS berichten bevatten per zending 1 functioneel bericht. Hierdoor is de overhead van het ebMS protocol voor de ontvangende partij relatief hoog.
 
 De berichtuitwisseling in de keten was oorspronkelijk opgezet volgens asynchrone bevestiging. Bij de ketenintegratietest tussen beide partijen kwamen verwerkingsproblemen aan de ontvangende kant aan het licht. In onderling overleg tussen de ketenpartners is afgesproken om de ebMS2 uitwisseling zo in te stellen dat acknowledgements synchroon verstuurd worden. Hierna verliep de uitwisseling volgens de afgesproken eisen aan capaciteit, performance en betrouwbaarheid.
+</aside>
 
 ### Voorwaarden voor toepassen van het synchrone bevestiging
 
-- Scope: Dit profiel is alleen geldig voor de Digikoppeling ebMS2 RM-profielen
-
-- Aanleiding: Door omvang van het volume van uitwisseling van berichten in beperkte tijd bestaan verwerkingsproblemen bij (een van beide) providers. Asynchrone uitwisseling van berichten binnen het ebMS profiel blijft de defaultmodus. Dus als de verwerking probleemloos verloopt is er geen reden om over te gaan op synchrone uitwisseling.
-
-- Voorwaarde: De Digikoppeling oplossing van beide partijen ondersteunen het instellen van SyncReplymode op mshSignalsOnly. Het instellen van deze mode kan dus niet eenzijdig worden opgelegd.
+- Scope:
+  - Dit profiel is alleen geldig voor de Digikoppeling ebMS2 RM-profielen
+- Aanleiding:
+  - Door omvang van het volume van uitwisseling van berichten in beperkte tijd bestaan verwerkingsproblemen bij (een van beide) providers. Asynchrone uitwisseling van berichten binnen het ebMS profiel blijft de defaultmodus. Dus als de verwerking probleemloos verloopt is er geen reden om over te gaan op synchrone uitwisseling.
+- Voorwaarde:
+  - De Digikoppeling oplossing van beide partijen ondersteunen het instellen van SyncReplymode op mshSignalsOnly. Het instellen van deze mode kan dus niet eenzijdig worden opgelegd.
 
 <aside class="note">
     Indien de berichtuitwisseling via een intermediary verloopt dient deze ook de SyncReplymode te ondersteunen om de synchrone communicatie tussen partijen mogelijk te maken.
 </aside>
 
 ## EB016 Correlatie van berichten
 
-Voor het correleren van berichten in ebMS2 spelen de elementen *Messageid*, *ConversationId* en *RefToMessageId* een rol. Het gebruik van de combinatie *MessageId* en *RefToMessageId* en het *ConversationId* dienen verschillende doelen.
+Voor het correleren van berichten in ebMS2 spelen de elementen *Messageid*, *ConversationId* en *RefToMessageId* een rol. Het gebruik van de combinatie *MessageId* en *RefToMessageId* en het *ConversationId* dienen verschillende doelen. Deze 2 doelen zijn hieronder uitgewerkt:
 
 ### Response op een specifiek request
 
 *Messageid* en *RefToMessageId* worden gebruikt om heel specifiek aan te geven op welke request een response wordt gegeven. *RefToMessageId* wordt dus gebruikt om de relatie tussen een ebMS bericht en het daarop volgende ACK of NACK bericht aan te geven, een protocol gerelateerde relatie.
 
-
 <aside class="example">
 Voor een terugmelding  op de GBA met MessageId 1234 moet de GBA in het antwoord op deze terugmelding het RefToMessageId 1234 gebruiken. Zo zijn request en response onlosmakelijk met elkaar verbonden. Normaal gesproken worden geen verdere antwoorden op een dergelijke melding terugverwacht waardoor het bericht met het RefToMessageId ook vaak de transactie beëindigt.
 </aside>