Post on 09-Aug-2020
© Copyright 2019 Netcompany. Alle rettigheder forbeholdes.
D0180 - INTEGRATIONSDESIGN FOR DATALEVERANDØR
Version:
1.6
Status:
Endelig
Godkender:
Forfatter:
DIGST – ORKESTRERINGSKOMPONENT
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 2
Dokumenthistorik
Version Dato Forfatter Status Bemærkninger
1.0 17.01.2019 Endelig -
1.1 23.01.2019 Endelig Tekstuelle rettelser
1.2 22.02.2019 Endelig
Rettelser til 2.2.1.2 (opdateret format af data-parameter), tilføjet API-nøgler til Sikkerhed
1.3 16.04.2019 Endelig
Opdateret 2.1.1.1 og 2.1.1.2 (for at håndtere ydelsesdata) og tilføjet nyt afsnit 2.1.1.4 med hent ydelsesdata-metode
1.4 23.04.2019 Endelig
Tilføjet CPR-nummer til request data i hent sagsdata-metode og hent ydelsesdata-metode
1.5 22.05.2019 Endelig
Tilføjet afsnit om brugersikkerhed samt udstillet service for ledetekster
1.6 12.06.2019 Endelig Opdateret pba. review-kommentarer fra DIGST
Referencer
Reference Titel Forfatter Version
FDM 1.3 Fælles datamodel 0.3
JSONP
JavaScript Object Notation (JSON) Patch
(https://tools.ietf.org/html/rfc6902 –
set den 23. januar 2019)
April 2013
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 3
Indholdsfortegnelse
1 Introduktion....................................................................................................................................................... 4 1.1 Datavalidering .............................................................................................................................................. 4
2 Integration med datakilde .................................................................................................................................. 4 2.1 Hentning af borger-data ............................................................................................................................... 4
2.1.1 Servicebeskrivelser ........................................................................................................................................ 5 2.1.1.1 Hent borger-data .............................................................................................................................. 5 2.1.1.2 Hent borger-data (specifik kommune) .............................................................................................. 6 2.1.1.3 Hent sagsdata ................................................................................................................................... 9 2.1.1.4 Hent ydelsesdata .............................................................................................................................. 10
2.1.2 BrugervendtSag ............................................................................................................................................. 12 2.1.3 Cpr-nummer-format ...................................................................................................................................... 12 2.1.4 BorgerDataType ............................................................................................................................................ 12
2.2 Borger-filtrering ........................................................................................................................................... 12 2.2.1 Metoder til håndtering af data i CPR-liste ..................................................................................................... 12
2.2.1.1 Tilføj/slet borgere ............................................................................................................................. 12 2.2.1.2 Ryd listen og tilføj borgere ................................................................................................................ 14
2.3 Ledetekster .................................................................................................................................................. 16 2.3.1 Hent ledetekster ............................................................................................................................................ 16
3 Sikkerhed ........................................................................................................................................................... 17 3.1 Udstillet service ........................................................................................................................................... 17 3.2 Dataleverandørers udstillede services .......................................................................................................... 17 3.3 Understøttelse af IDWS ................................................................................................................................ 17
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 4
1 Introduktion Dette dokument beskriver den integationsaftale, som datakilder, der integrerer mod Orkestreringskomponent skal overholde,
når de udstiller data om en borger, som udstilles til portaler via Orkestreringskomponentet. Formålet med denne dataaftale er,
at det giver Orkestreringskomponentet mulighed for at returnere et samlet, ensartet svar til portaler både ift. sammenstilling af
svar såvel som håndtering af fejlscenarier i de enkelte services.
1.1 Datavalidering
Orkestreringskomponenten validerer alle svar fra dataleverandøren mod [FDM] for at sikre, at der kun sendes valide formater
tilbage til kaldende portaler. I tilfælde af, at modtaget data fra en dataleverendør ikke validerer mod [FDM], vil
Orkestreringskomponenten sende en fejlmeddelelse som svar for den givne dataleverandør til den kaldende portal.
2 Integration med datakilde
2.1 Hentning af borger-data
Det er muligt for Orkestreringskomponent at hente data om en borger fra en datakilde, der udstiller data til
Orkestreringskomponent jf. dataaftalen i dette dokument.
For at Orkestreringskomponent kan interagere med en datakilde, skal datakilden udstille de for datakilden relevante services, der
er beskrevet i de følgende afsnit.
ORKESTRERINGS-
KOMPONENT DATAKILDE
Hent borger-data
Data
Hent sagsdata
Sagsdata
Hent ydelsesdata
Ydelsesdata
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 5
2.1.1 Servicebeskrivelser
2.1.1.1 Hent borger-data
Titel Hent borger-data
Beskrivelse
Henter data, der gælder for en borger med det cpr-nummer, der er angivet i kaldet. Det er
muligt at hente enten oversigtsdata (liste med basisinformation) eller detaljeret data (liste med
detaljeret information). Det er også muligt at specificere datatype for kun at hente sager, kun at
hente ydelser eller begge dele på en gang.
URL Valgfri, f.eks. /borgerdata
Method POST
URL params n.a.
HTTP Headers Accept: application/json or application/xml
Content-Type: application/json or application/xml
Custom header
"X-TransactionId" : [string]
X-TransactionId – ID for transaktionen
Data params
{
"cpr" : [string],
"detailedLevel" : [boolean]
"dataType" : [BorgerDataType]
}
cpr – borgerens CPR-nummer
detailedLevel – specificerer, om der skal hentes grundlæggende eller detaljerede data fra
datakilden (OPTIONAL, default værdi: false)
dataType – specificerer, hvilken type af data skal returneres – alt data, kun sager eller kun
ydelser (OPTIONAL, default værdi: alt data)
Success response
Code: 200 (OK)
Content:
{
"data" : [Dictionary<BorgerDataType, List<BrugervendtSag>>]
}
data – data om borgeren, der følger ”Fælles datamodel”
Code: 204 (No content)
Hvis der ikke er noget data knyttet til cpr-nummeret, der er angivet i kaldet
Error response Code: 400 (Bad request)
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 6
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Code: 401 (Unauthorized)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Code: 500 (Internal Server Error)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Sample call
$.ajax({
url : "/borgerdata",
dataType : "json",
data : {
"cpr" : "1501999511",
"detailedLevel" : true,
"dataType" : 0
},
type : "POST",
success : function(r) {
console.log(r);
}
});
2.1.1.2 Hent borger-data (specifik kommune)
Titel Hent borger-data (specifik kommune)
Beskrivelse
Henter alt data, der gælder for en borger med det angivne cpr-nummer indenfor den kommune,
der er angivet i kaldet. Det er muligt at hente enten oversigtsdata (sagsliste med basis-
information om sager) eller detaljeret data (sagsliste med detaljeret information om sager). Det
er også muligt at specificere data type for kun at hente sager, kun at hente ydelser eller begge
dele på en gang.
URL Valgfri, f.eks. /borgerdata
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 7
Method POST
URL params n.a.
HTTP Headers Accept: application/json or application/xml
Content-Type: application/json or application/xml
Custom header
"X-TransactionId" : [string]
X-TransactionId – ID for transaktionen
Data params
{
"cpr" : [string],
"municipalityCode" : [string],
"detailedLevel" : [boolean],
"dataType" : [BorgerDataType]
}
cpr – borgerens CPR-nummer
municipalityCode –kommunekode for den kommune, der ønskes data fra
detailedLevel – specificerer, om der skal hentes grundlæggende eller detaljerede data fra
datakilden (OPTIONAL, default værdi: false)
dataType – specificerer, hvilken type af data skal returneres – alt data, kun sager eller kun
ydelser (OPTIONAL, default værdi: alt data)
Success response
Code: 200 (OK)
Content:
{
"data" : [Dictionary<BorgerDataType, List<BrugervendtSag>>]
}
data – data om borgeren, der følger ”Fælles datamodel”
Code: 204 (No content)
Hvis der ikke er noget data knyttet til cpr-nummeret, der er angivet i kaldet
Error response
Code: 400 (Bad request)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Code: 401 (Unauthorized)
Content:
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 8
{
"message" : [string]
}
message – besked, der beskriver fejlen
Code: 500 (Internal Server Error)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Sample call
$.ajax({
url : "/borgerdata",
dataType : "json",
data : {
"cpr" : "1501999511",
"municipalityCode" : "101",
"detailedLevel" : true,
"dataType" : 0
},
type : "POST",
success : function(r) {
console.log(r);
}
});
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 9
2.1.1.3 Hent sagsdata
Titel Hent sagsdata
Beskrivelse Henter detaljeret data om en sag, der har det ID, der er angivet i kaldet.
URL Valgfri, f.eks. /sagsdata
Method POST
URL params n.a.
HTTP Headers Accept: application/json or application/xml
Content-Type: application/json or application/xml
Custom header
"X-TransactionId" : [string]
X-TransactionId – ID for transaktionen
Data params
{
"sagsId" : [string]
"cpr" : [string]
}
sagsId – sagens id
cpr – borgerens CPR-nummer
Success response
Code: 200 (OK)
Content:
{
"data" : [BrugervendtSag]
}
data – sagsdata, der følger ”Fælles datamodel”
Code: 204 (No content)
Hvis der ikke er nogen sag med det i kaldet angivne id
Error response
Code: 400 (Bad request)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Code: 401 (Unauthorized)
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 10
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Code: 500 (Internal Server Error)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Sample call
$.ajax({
url : "/sagsdata",
dataType : "json",
data : {
"sagsId" : "fa3ca005-3d12-40e5-ba80-aa71b6df1db2",
"cpr" : "1501999511"
},
type : "POST",
success : function(r) {
console.log(r);
}
});
2.1.1.4 Hent ydelsesdata
Titel Hent ydelsesdata
Beskrivelse Henter detaljeret data om en ydelse, der har det ID, der er angivet i kaldet.
URL Valgfri, f.eks. /ydelsesdata
Method POST
URL params n.a.
HTTP Headers Accept: application/json or application/xml
Content-Type: application/json or application/xml
Custom header
"X-TransactionId" : [string]
X-TransactionId – ID for transaktionen
Data params {
"ydelsesId" : [string],
"cpr" : [string]
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 11
}
ydelsesId – ydelsens id
cpr – borgerens CPR-nummer
Success response
Code: 200 (OK)
Content:
{
"data" : [BrugervendtSag]
}
data – ydelsesdata, der følger ”Fælles datamodel”
Code: 204 (No content)
Hvis der ikke er nogen ydelse med det i kaldet angivne id
Error response
Code: 400 (Bad request)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Code: 401 (Unauthorized)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Code: 500 (Internal Server Error)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Sample call
$.ajax({
url : "/ydelsesdata",
dataType : "json",
data : {
"ydelsesId" : "fa3ca005-3d12-40e5-ba80-aa71b6df1db2",
"cpr" : "1501999511"
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 12
},
type : "POST",
success : function(r) {
console.log(r);
}
});
2.1.2 BrugervendtSag
BrugervendtSag er en klasse, der indeholder al information om sager, der er relateret til borgeren. Detaljeret beskrivelse af data
er inkluderet i [FDM].
2.1.3 Cpr-nummer-format
Cpr-nummeret skal sendes som en string uden bindestreg, f.eks. ”2703980243”.
2.1.4 BorgerDataType
BorgerDataType er en flag-enum, der specificerer, hvilken datatype der skal hentes fra datakilden.
2.2 Borger-filtrering
Det er muligt for en datakilde at give Orkestreringskomponenten information om hvilke CPR-numre, datakilden skal kaldes for.
Orkestreringskomponenten har således en CPR-liste og foretager filtrering vha. denne, så Orkestreringskomponent kun kalder
datakilden, når borgerens CPR-nummer er til stede i databasen for den pågældende dataklide.
Om der skal foretages CPR-filtrering er en optionel valgmulighed per datakilde og konfigureres i Orkestreringskomponenten
under tilføjelse af datakilden.
Datakilden har mulighed for at opdatere borgere, der er gemt i CPR-listen, ved hjælp af de metoder, der er beskrevet i de
følgende afsnit.
2.2.1 Metoder til håndtering af data i CPR-liste
2.2.1.1 Tilføj/slet borgere
Titel Tilføj/slet borgere
[Flags]
enum BorgerDataType
{
Alle = 0,
Sager = 1,
Ydelser = 2
}
ORKESTRERINGS-
KOMPONENT DATAKILDE
Tilføj/slet borgere
Ryd listen og tilføj borgere
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 13
Beskrivelse Tilføjer/sletter en liste af cpr-numre til/fra CPR-listen.
URL /borgerlist
Method PATCH (læs mere om JSON-PATCH i [JSONP])
URL params n.a.
HTTP Headers Accept: application/json or application/xml
Content-Type: application/json or application/xml
Custom header
"X-TransactionId" : [string]
X-TransactionId – ID for transaktionen
Data params
[
{
"op" : [string],
"value" : [string]
}
]
Operation – handling, der skal udføres på cpr-nummer, der er angivet i ”value”-feltet,
understøttede værdier:
”add” – tilføj cpr-nummer til listen
”remove” – fjern cpr-nummer fra listen
Value – cpr-nummer
Success response Code: 200 (OK)
PATCH-operation er atomic. Kode 200 sendes kun, når alle operation er succesfulde.
Error response
Code: 400 (Bad request)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Code: 401 (Unauthorized)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 14
Code: 500 (Internal Server Error)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Sample call
$.ajax({
url : "/borgerlist",
dataType : "json",
data : [
{
"op" : "add",
"value" : "1501999511"
},
{
"op" : "remove",
"value" : "2703980243"
}
]
type : "PATCH",
success : function(r) {
console.log(r);
}
});
2.2.1.2 Ryd listen og tilføj borgere
Titel Ryd listen og tilføj borgere
Beskrivelse
Erstatter listen af cpr-numre, der er gemt i CPR-listen, med listen, der er angivet i kaldet. Hvis
listen i kaldet er tom, bliver alle cpr-numre, der er relevante for datakilden, fjernet fra CPR-
listen.
URL /borgerlist
Method PUT
URL params n.a.
HTTP Headers Accept: application/json or application/xml
Content-Type: application/json or application/xml
Custom header
"X-TransactionId" : [string]
X-TransactionId – ID for transaktionen
Data params
{
"cprList" :
[
[string]
]
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 15
}
cprList – liste af cpr-numre, der skal erstatte listen
Success response Code: 200 (OK)
Error response
Code: 400 (Bad request)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Code: 401 (Unauthorized)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Code: 500 (Internal Server Error)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Sample call
$.ajax({
url : "/borgerlist",
dataType : "json",
data :
{
"cprList" :
[
"1501999511",
"2703980243",
"1305004037",
"0511830087"
]
},
type : "PUT",
success : function(r) {
console.log(r);
}
});
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 16
2.3 Ledetekster
Orkestreringskomponenten udstiller en simpel service, hvor der kan hentes et katalog af ledetekster, som skal benyttes i svaret
fra en dataleverandør for felter i FDM-formatet.
Det er tanken, at en dataleverandør med passende mellemrum kalder Orkestreringskomponenten for opdatering af
ledeteksterne. Dette kunne eksempelvis være en gang i timen.
2.3.1 Hent ledetekster
Titel Hent ledetekster
Beskrivelse Giver en liste af ledetekster til brug i sammenhæng med [FDM]
URL /ledetekster
Method GET
URL params n.a.
HTTP Headers Accept: application/json or application/xml
Content-Type: application/json or application/xml
Custom header
"API-key" : [string]
API-key – Aftalt API-nøgle for den givne dataleverandør
Reply
{
"labels" :
[
attribute: [string],
label: [string]
]
}
labels – liste af key-values for attributter og tilhørende ledetekst
Success response Code: 200 (OK)
Error response
Code: 400 (Bad request)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
Code: 401 (Unauthorized)
Content:
{
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 17
"message" : [string]
}
message – besked, der beskriver fejlen
Code: 500 (Internal Server Error)
Content:
{
"message" : [string]
}
message – besked, der beskriver fejlen
3 Sikkerhed I dette afsnit beskrives sikkerhedsperspektiver i løsningen. Det drejer sig dels om sikkerhed i forbindelse med udstilling og
aftagelse af udstillede services og dels et afsnit omkring Orkestreringskomponentens garanti til dataleverandører for, at der kun
foretages forespørgelser for et CPR-nummer, når det er borgeren selv, der har initieret det.
3.1 Udstillet service
Den service, Orkestreringskomponenten udstiller omkring ledetekster, benytter følgende sikkerhedsmetodikker:
API-nøgle, der er unik per dataleverandør – benyttes dels til statistiske formål såvel som en simpel blokering af
utilsigtet brug af den udstillede service
Understøttelse af alle TLS-versioner
3.2 Dataleverandørers udstillede services
Det er muligt for Orkestreringskomponent at benytte følgende sikkerhedsmetodikker:
FOCES – klientcertifikater, der bruges til at identificere Orkestreringskomponenten ved kald til datakilde samt til
verifikation af svar
IP-filtrering (Orkestreringskompont kalder altid fra fast udgående IP-adresse)
Understøttelse af alle TLS-versioner
Brug af API-nøgler
Det vil være et valg for den enkelte dataleverandør, hvordan sikkerheden endeligt implementeres, men det er dataleverandørens
ansvar at sikre, at deres udstillede services er tilgængelige for Orkestreringskomponenten, men samtidig er beskyttet mod
uretmæssig brug.
3.3 Understøttelse af IDWS
Orkestreringskomponenten garanterer overfor dataleverandører, at der kun foretages kald til deres udstillede services på vegne
af reelle, indloggede borgere. Dette sker gennem brug af NemLog-ins IDWS-service, som er et sikkerhedskrav til integrationen
mellem en kaldende portal og Orkestreringskomponenten. Ved hjælp af IDWS-servicen for en given portal verificerer
D0180 - Integrationsdesign for dataleverandør
© 2019 Netcompany 18
Orkestreringskompnenten, at portaler kun kalder på vegne af borgere med valide NemLog-in-sessioner. Udløb for
Orkestreringskomponentens verificering af gyldig borger-session sættes efter NemLog-ins best-practices.