D0180 - Integrationsdesign for dataleverandør · detailedLevel – specificerer, om der skal...

© 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

https://tools.ietf.org/html/rfc6902



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



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



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)



Content:

{

"message" : [string]

}

message – besked, der beskriver fejlen

Code: 401 (Unauthorized)

Content:

{


}


Code: 500 (Internal Server Error)

Content:

{


}


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



Method POST

URL params n.a.



Custom header



Data params

{

"cpr" : [string],

"municipalityCode" : [string],

"detailedLevel" : [boolean],

"dataType" : [BorgerDataType]

}


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”


Hvis der ikke er noget data knyttet til cpr-nummeret, der er angivet i kaldet

Error response

Code: 400 (Bad request)

Content:

{


}



Content:



{


}



Content:

{


}


Sample call

$.ajax({

url : "/borgerdata",

dataType : "json",

data : {

"cpr" : "1501999511",

"municipalityCode" : "101",

"detailedLevel" : true,

"dataType" : 0

},

type : "POST",


console.log(r);

}

});



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.



Custom header



Data params

{

"sagsId" : [string]

"cpr" : [string]

}

sagsId – sagens id


Success response

Code: 200 (OK)

Content:

{

"data" : [BrugervendtSag]

}

data – sagsdata, der følger ”Fælles datamodel”


Hvis der ikke er nogen sag med det i kaldet angivne id

Error response


Content:

{


}





Content:

{


}



Content:

{


}


Sample call

$.ajax({

url : "/sagsdata",

dataType : "json",

data : {

"sagsId" : "fa3ca005-3d12-40e5-ba80-aa71b6df1db2",

"cpr" : "1501999511"

},

type : "POST",


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.



Custom header



Data params {

"ydelsesId" : [string],

"cpr" : [string]



}

ydelsesId – ydelsens id


Success response

Code: 200 (OK)

Content:

{

"data" : [BrugervendtSag]

}

data – ydelsesdata, der følger ”Fælles datamodel”


Hvis der ikke er nogen ydelse med det i kaldet angivne id

Error response


Content:

{


}



Content:

{


}



Content:

{


}


Sample call

$.ajax({

url : "/ydelsesdata",

dataType : "json",

data : {

"ydelsesId" : "fa3ca005-3d12-40e5-ba80-aa71b6df1db2",

"cpr" : "1501999511"



},

type : "POST",


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



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.



Custom header



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


Content:

{


}



Content:

{


}





Content:

{


}


Sample call

$.ajax({

url : "/borgerlist",

dataType : "json",

data : [

{

"op" : "add",

"value" : "1501999511"

},

{

"op" : "remove",

"value" : "2703980243"

}

]

type : "PATCH",


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.



Custom header



Data params

{

"cprList" :

[

[string]

]



}

cprList – liste af cpr-numre, der skal erstatte listen


Error response


Content:

{


}



Content:

{


}



Content:

{


}


Sample call

$.ajax({

url : "/borgerlist",

dataType : "json",

data :

{

"cprList" :

[

"1501999511",

"2703980243",

"1305004037",

"0511830087"

]

},

type : "PUT",


console.log(r);

}

});



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.



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


Error response


Content:

{


}



Content:

{




}



Content:

{


}


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



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.

D0180 - Integrationsdesign for dataleverandør · detailedLevel – specificerer, om der skal...

Documents

Transcript of D0180 - Integrationsdesign for dataleverandør · detailedLevel – specificerer, om der skal...