Aansluiten
Inhoud
DSP 2.0
Technische informatie
DSP 2.0 is opgebouwd in een REST/JSON architectuur. Zie deze link voor de documentatie van DSP 2.0
- Authenticatie richting het DSP: OAuth2.0 met de client credentials flow.
- Berichten richting het DSP (Deelnemer => DSP): Een client die gebruikt maakt van bovenstaande authenticatie om berichten te sturen richting het DSP.
- Ontvangen van berichten (DSP => Deelnemer): Het DSP pusht berichten richting een door de deelnemer in te richten server. Verkeer vanuit het DSP richting de deelnemer gaat ook met OAuth2.0. Daarom moet er ook een Token URL, een Client ID, en een Client Secret worden aangeleverd waarmee het DSP zich bij de deelnemer kan authoriseren.
Proces en specificatie
Het functionele proces is met 2 uitzonderingen gelijk aan DSP 1.36, de specificatie is voor zover mogelijk gelijk aan DSP 1.36. Zie de changelog voor de aanpassingen in de translatie van de XSD naar de YAML.
De proces changes zijn:
1. Annulering is alleen nog mogelijk na Bijstelling (met reden anders dan 'Conversie')
2. Hergebruik van OpdrachtID is niet meer mogelijk
Bijlagen
- Bijlagen worden gedeeld met een referentie van de bijlage in het bericht. Zie de functionele procesplaat voor het bijlageproces en hoe we verwachten dat de deelnemer dit implementeert.
- Er geldt een maximum van 50MB (51200 KB) per geüploade bijlage.
IP adressen DSP 2.0
QAS omgeving:
18.184.62.229
18.196.138.136
18.197.139.195
TEST omgeving:
3.120.99.75
35.156.133.98
35.157.145.91
Vraag functioneel beheer naar de IP adressen voor de PRD omgeving.
DSP 2.0 testtool locatie
Vanaf DSP 2.0 gebruiken we niet Analytics, maar een andere omgeving voor DSP testwerk. Deze testtool kan men gebruiken voor deelnemer-DSP connectie.
De locatie van testtool voor DSP 2.0 is https://qas-testtool.dsplatform.nl/opdracht
Technische demo's DSP 2.0
Hierbij de link naar alle technische demo's over DSP 2.0 (presentaties en opnames).
DSP 1.36
Technische vereisten
Het kunnen versturen en ontvangen van berichten via SOAP 1.1 en het kunnen communiceren over een met TLS 1.2 beveiligde verbinding zijn vereist om via Webservices berichten uit te kunnen wisselen met het DSP. Hierbij wordt het gebruik van een servicebus aangeraden, maar is niet verplicht. Voor het uitwisselen van bijlagen ondersteunt het DSP zowel SwA (SOAP with Attachments) als MTOM.
Certificaten
Het voor TLS 1.2 benodigde server certificaat moet gesigneerd zijn door een officiële CA (Certificate Authority).
Aanmelden nieuwe deelnemer
In deze alinea wordt beschreven welke fases er worden doorlopen om een deelnemer aan te sluiten op het DSP.
Het onderstaande stappenplan wordt als leidraad gebruikt en benoemt de te doorlopen stappen om te kunnen koppelen met het DSP.
Sommige stappen zijn optioneel, deze zijn als dusdanig kenbaar gemaakt en het is aan de deelnemer om te bepalen en aan te geven welke stappen we met elkaar zullen doorlopen.
Beginfase
In deze fase hebben we in eerste instantie overleg met elkaar over de mogelijkheden en tijdslijnen.
- Uitgangspunten implementatie bespreken met de Product Owner.
- - Hierbij bespreken we welke ambities/doelen u heeft en hoe het DSP u daarbij kan helpen.
- Hoofdlijnen planning en eventuele fasering.
- - We stemmen met elkaar af welke omgeving u wilt koppelen met het DSP en welke tijdslijnen u daarbij voor ogen heeft.
Informatiefase
Van de nieuwe deelnemer wordt verwacht over gedegen kennis te beschikken inzake het uitwisselen van berichten via Webservices.
De eerste stap voor nieuwe deelnemers is het invullen van het Aanmeldingsformulier, en dit via een Service Request in te dienen
Functioneel beheer neemt vervolgens via het Service Request contact op met de deelnemer om de koppeling tot stand te brengen.
In eerste instantie zullen we met elkaar de benodigde informatie uitwisselen om zo aan beide zijden de configuratie van de endpoints op orde te kunnen maken.
Eventuele opvolgende informatie wordt ook via het Service Request uitgewisseld.
- De basis informatie om aan te sluiten kunt u terugvinden in onze Wiki.
- Wij ontvangen graag de volgende informatie van u:
- - Gewenste manier van bijlagen uitwisselen: via SOAP with Attachments (SwA) of via Message Transmission Optimization Mechanism (MTOM)
- - Gewenste organisatienaam: ten behoeve van de waardelijsten aangaande de netbeheerders en aannemers.
- - E-mail adres contactpersoon. Dit adres wordt gebruikt voor e-mail notificaties bij problemen met het afleveren van DSP berichten bij u.
- - Technische gegevens van de omgevingen en systemen:
- IP-adressen en poortnummers (uw inbound IP-adressen t.b.v. whitelisting) per omgeving.
- Indien niet extern beschikbaar: uw server certificaat.
- Gewenste manier van authenticeren bij zowel het DSP als uw eigen servers (door het DSP): Basic en/of Certificate.
- - In het geval van Certificate authenticatie bij het DSP: graag het client certificaat meesturen met deze informatie. N.B. Het DSP ondersteunt enkel het ontvangen van het 'leaf'-certificaat. (Indien de hele chain wordt meegestuurd werkt Certificate authenticatie om technische redenen niet)
- - In het geval van Certificate authenticatie op uw servers: graag aangeven of u een client certificaat verstrekt of dat het Client certificaat van het DSP gebruikt kan/mag worden.
- Uw endpoints voor de verschillende berichttypen.
- De volgende informatie is vanuit het DSP beschikbaar om de koppeling tot stand te brengen:
- - Technische bestanden (XSD's en WSDL's) van de te implementeren berichtversie.
- - IP-adressen en poortnummers van onze omgevingen.
- - Endpoints voor de verschillende berichttypen. Connectiviteits tabje DSP-Analytics
- - Credentials t.b.v. de methode Basic authenticatie indien u geen gebruik wenst te maken van Certificate authenticatie bij het DSP.
- - Ons client certificaat indien u wil dat het DSP Certificate authenticatie gebruikt om zich aan te melden op uw server(s) en u zelf geen certificaat verstrekt. Connectiviteits tabje DSP-Analytics
Oplevering-/testfase
Tijdens deze fase kan er, afhankelijk van de planning en de omgevingen waaraan gekoppeld wordt, worden gestart met het uitvoeren van de eerste testen in de vorm van connectiviteitstesten.
Zorg er voor dat de volgende checks zijn uitgevoerd (per omgeving - PRD & QAS):
- Firewall aanpassingen voor binnenkomend en uitgaand verkeer van en naar de betreffende omgeving van het DSP zijn doorgevoerd.
- Eventuele ontbrekende CA-certificaten zijn geïmplementeerd in de benodigde key stores.
- Controleer of uw endpoints, die u eerder aan ons heeft doorgegeven, nog overeenkomen met de endpoints die gebruikt worden door het DSP om berichten bij u af te leveren.
Functioneel Beheer is uw eerste aanspreekpunt voor vragen en opmerkingen die betrekking hebben op de connectiviteitstesten.
Deze vragen en opmerkingen kunt u stellen via het Service Request.
Let op:
Er zal geen ondersteuning zijn op de XML bestanden die door de deelnemer worden ingeladen. De deelnemer dient zelf over de kennis te beschikken om valide XML bestanden te genereren en is dan ook zelf verantwoordelijk voor de juistheid hiervan.
De deelnemer kan andere tooling zoals SoapUI gebruiken om een valide XML bericht te genereren.
Indien gewenst kan er een gezamenlijk testmoment worden afgestemd om de goede werking van de koppelingen te valideren.
Wanneer de connectiviteitstesten succesvol zijn gebleken en eventuele technische obstakels zijn weggenomen, staat het u vrij om ketentesten uit te voeren met ketenpartners die ook zijn gekoppeld met het DSP.
Deze testen dienen uitgevoerd te worden op de QAS (Quality Assurance System) - ook wel bekend als het acceptatie systeem van DSP.
Wanneer deze ketentesten succesvol zijn uitgevoerd op de QAS omgeving, geeft u hiervan een bevestiging in het service verzoek.
Vervolgens zal Mijnaansluiting uw organisatie op de DSP Productie omgeving inrichten en u hierover informeren via het service verzoek.
Hierna dient u in overleg met de ketenpartners (netbeheer/aannemer & Mijnaansluiting) het moment van live-gang af te stemmen.
Wanneer uw organisatie op de DSP Productie omgeving live staat, is het voor uw organisatie mogelijk om berichten naar het DSP te sturen en van het DSP te ontvangen.
Web service responses
Na het verwerken van een bericht door een deelnemer of het DSP wordt een synchrone respons (ontvangstbevestiging of SOAPFault bij fouten in verwerking) verstuurd. Zie Synchrone respons op ontvangen berichten voor meer informatie.
Authenticatie
Gewenste manier van authenticeren bij zowel het DSP als uw eigen servers (door het DSP): Basic en/of Certificate.
- In het geval van Certificate authenticatie bij het DSP: graag het client certificaat meesturen met deze informatie. N.B. Het DSP ondersteunt enkel het ontvangen van het 'leaf'-certificaat. (Indien de hele chain wordt meegestuurd werkt Certificate authenticatie om technische redenen niet)
- In het geval van Certificate authenticatie op uw servers: graag aangeven of u een client certificaat verstrekt of dat het Client certificaat van het DSP gebruikt kan/mag worden.
Gebruik SoapUI
SoapUI is een handig hulpmiddel bij het koppelen met het DSP. Met deze software kunnen deelnemers berichten die vanuit het eigen systeem worden gegenereerd toetsen t.o.v. de XSD’s. Ook biedt SoapUI de mogelijkheid om de interactie met het DSP/Aannemer/Netbeheerder te simuleren. Het ontvangen van een bericht van DSP in het eigen systeem kan worden gesimuleerd door het bericht te versturen vanuit SoapUI. Het verzenden van een bericht naar DSP kan worden gesimuleerd door het bericht te ontvangen in SoapUI middels een mockservice. Meer informatie over SoapUI is te vinden op: SoapUI - Getting Started