Innehåll
Innehållsförteckning | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Inledning
Om dokumentet
Denna beskrivning är ett tillägg av tjänstekontrakten i tjänstedomänen strategicresourcemanagement:persons:person. Dokumentet beskriver hur tjänstens funktionalitet för att hämta och ladda upp filer är uppbyggd. Funktionaliteten baseras på dokument ARK_0038 enligt RIV-TA standarden och där grundprincipen för att hämta filer bygger på en RIV-tjänst för att lista tillgängliga filer och en REST-tjänst för att hämta de filer som listas via RIV-tjänsten. Anrop mot tjänsterna sker med HTTPS (Mutual-TLS) och validering av certifikatet från tjänstekonsument utförs för att endast tillåta att tjänsten levererar data till tillåtna mottagare.
Konnektivitet
SOAP-tjänst för att lista tillgängliga filer är tillgängliga via Nationell Tjänsteplattform (NTjP). NTjP saknar dock stöd för REST-baserade tjänster vilket medför att REST-tjänst för att hämta filer (ladda upp/ta bort) enbart är tillgänglig genom direktaccess mot tjänsteproducent.
Info |
---|
Versionshantering av searchPersonsByFile i domänversion 3 och 4Vid Release 4.8, som införde domänversion 4 av Personuppgiftstjänsten, gjordes en driftsförändring som gav REST-tjänsten för searchPersonsByFile två versioner; en för vardera domänversion. |
...
REST-tjänsterna finns i olika version beroende på domänversionNotera att det i vissa fall finns olika versioner av REST-tjänsterna, för att vara kompatibla med olika domänversioner av Personuppgiftstjänsten. Läs mer under denna sidas avsnitt Versioner samt sidan Livscykel för versioner. |
Figur: Anrop först till tjänst i NTjP med SOAP och sedan direkt till tjänsten med REST för att hämta resultatet från första anropet.
Notering om HSA-id: Personuppgiftstjänstens REST-tjänster kontrollerar vid begäran om filnedladdning att det är systemet med samma HSA-id som beställt filen. Om anropande konsument använder ett mellanlager i anslutning till NTjP, såsom en lokal tjänsteplattform, är det då viktigt för konsumenten att korrekt populera headern x-rivta-original-originalserviceconsumerserviceconsumer-hsaid. Denna header skall ange det ursrungliga konsumerande systemets HSA-id, i enlighet med regel "Bevara ursprunglig avsändares identitet i http header" samt RIVTA Regel 23.
Beställning av behörighet
Personuppgiftstjänstens filhanteringstjänster är REST-tjänster som inte ingår i Inera NTjP. Behörighet för att använda dessa följer därför ett separat beställningsförfarande.
Beställning av behörighet till REST-tjänster görs genom att fylla i följande beställningsformulär, vilket skickas till Ineras kundtjänst på kundservice@inera.se. Ange i mailtexten att det gäller "Beställning Beställningen skickas som en bilaga i ett ärende till Inera. Välj att det gäller ”Personuppgiftstjänsten” och området ”Övrigt”. Ange i ärendetexten att det gäller ”Beställning av REST-tjänst för Personuppgiftstjänsten – se bilagabilaga”."
View file | ||
---|---|---|
|
HSA-id: Till skillnad från NTjP-baserade tjänstekontrakt så kommer behörighet till REST-tjänsterna alltid att utgå ifrån HSA-id hos det konsumerande systemet, inte ifrån HSA-id hos eventuellt mellanlager. Ange därför i beställningen av REST-tjänst alltid det konsumerande systemets HSA-id.
...
Användningsfall | Syfte | Ingående REST-tjänster |
Söka personuppgifter via fil | Begär en sökning på en bifogad lista med identiteter | SearchPersonsByFile GetPersonsByFile Order/Get |
Hämta resultatfil från kriteriesökning | Hämta resultat från en sökning kriteriesökning gjord via NTjP tjänstekontrakt som SearchPersonsForProfileByOrder eller SearchPersonsForProfileByOrderUnrestricted, vilket genererat en resultatfil. | Order/Get |
Hantering av bilagor för reservidentiteter | Inkludera bilagd fil som styrker en reservidentitet | Attachment/Put Attachment/Get Attachment/Delete |
Användningsfall
Filhantering förekommer i följande användningsfall inom Personuppgiftstjänsten:
Söka personuppgifter via fil: SearchPersonsByFile och GetPersonsByFile
Hämta resultat för asynkron personsökning: SearchPersonsForProfileByOrder, SearchPersonsByFile och SearchPersonsByFileGetPersonsByFile
Hantering av bilagor för reservidentiteter: Hämta, ladda upp samt ta bort
Användningsfall 2 och delvis 3 följer flödet som beskrivs i ARK_0038 Refererad bilaga, medans detta inte är applicerbart i användningsfallen 1 och delvis 3 vid uppladdning av bilagor. Flöden för samtliga användningsfall specificeras i följande avsnitt.
Söka personuppgifter via fil: GetPersonsByFile/SearchPersonsByFile
Funktionen Funktionerna finns endast som restricted-variant. Returnerar alltså inte adress m.m på sekretessmarkerade personposter.
Flödet startar med att att en lista med personidentiteter behöver uppdateras. Listan upprättas som en radbruten CSV-fil där identiteterna anges med personid och personid-typ (OID) separerade med semikolon. Ex: 191212121212;1.2.752.129.2.1.3.1
Filen laddas upp via någon av REST-metoden metoderna SearchPersonsByFile eller GetPersonsByFile, som vid lyckad uppladdning returnerar ett Order-Id. Detta Order-Id används som inparameter till tjänsten GetFilesForOrderId som returnerar ett svar om var den resulterande filen kan hämtas.
Om ordern inte är redo för nedladdning än så returneras inget svar, försök senare. Då ordern läggs på kö så kan väntetiden variera mycket. Kontakta supporten om din order inte är redo efter 24h.
OBS: Filer skapade via personsök är garanterat tillgängliga i ett dygn, därefter rensas dom automatiskt bort från Personuppgiftstjänsten. Filer som har hämtats kan rensas bort tidigare.
Den slutgiltiga filen som hämtas är en zippad fil innehållande en XML med det urval som efterfrågats, inbäddade i en GetPersonsForProfileResponse. Notera där följande:
Innehållet kommer att skilja sig från hur svaret ser ut i en GetPersonsForProfileResponse som uppkommit efter fråga mot tjänstekontraktet GetPersonsForProfile, enligt följande: I svaret som genererats via SearchPersonsByFile kommer endast en RequestedPersonRecord att levereras för de personposter som hittades i databasen. Detta i kontrast mot svaren från GetPersonsForProfile, där varje efterfrågad personpost kommer att få en RequestedPersonRecord oavsett om personposten hittades eller ej.
SearchPersonsByFile har ej stöd för sökning mot personposter med testIndicator=true, dvs personidentiteter som i SearchPersonsByFile och getPersonsByFile har ej stöd för sökning mot personposter med testIndicator=true, dvs personidentiteter som i testmiljö kallas testpersoner och i produktionsmiljö kallas valideringspersoner. En sökning mot sådan identitet kommer inte att returnera någon RequestedPersonRecord personRecord oavsett om personposten finns i databasen eller ej, dvs svaret ser alltid ut som att ingen träff fanns på denna identitet. För tester av någon av SearchPersonsByFile dessa funktioner behöver istället testpersoner med testIndicator=false användas.
...
Bild: Exempel på ett svar där träff ficks på ett personid.
...
Parametrar
Namn | Beskrivning |
---|---|
profile | Obligatorisk parameter för vilken profil som önskas i svaret. Se TKB för beskrivning av profilerna P1-P5. Observera att profilen skall anges med versalt P. Exempel: P1 |
fromDate | Valfri parameter för det datum man är intresserad av förändringar från och med baserat på fältet version i personposten. Exempel: 2021-10-12T00:00:00 |
maxResultsPerFile | Valfri parameter för max antal personposter per fil. Ej angivet så returneras alltid resultatet i endast en fil. Detta värde får ej vara lägre än 500. Exempel: 1000 |
primaryidentities primaryidentity | Valfri parameter som om satt till true gör att endast personposter som är markerad som huvudidentitet inkluderas i svaret. En efterfrågad personpost som inte är en huvudidentitet kommer då varken att generera en requestedPersonalIdentity eller en personRecord i svarsfilen. Exempel: true |
...
URL
REST-tjänsten SearchPersonsByFile searchPersonsByFile finns i två versioner och anropas via två olika , samt en tredje version som döpts om till getPersonsByFile. Dessa anropas via tre olika url:er. Det som skiljer versionerna åt är att de är kompatibla med olika versioner av domänen strategicresourcemanagement:persons:person.
URL för Testmiljö
https://api.pu.ineratest.org:443/purest/searchPersonsByFile searchPersonsByFile - kompatibel med domänversion 3.
https://api.pu.ineratest.org:443/purest/v2/searchPersonsByFile searchPersonsByFile - kompatibel med domänversion 4.
Exempel
Via cURL
...
Request
...
Response
...
...
...
getPersonsByFile - kompatibel med domänversion 5.
URL för Prod-miljö
https://api.pu.inera.se:443/purest/searchPersonsByFile - kompatibel med domänversion 3.
https://api.pu.inera.se:443/purest/v2/searchPersonsByFile - kompatibel med domänversion 4.
https://api.pu.inera.se:443/purest/getPersonsByFile - kompatibel med domänversion 5.
Exempel
Via cURL
Resultatfilerna är ZIP:ade och innehåller en XML-fil med det urval som efterfrågats. Formatet som specificeras i TKB och XSD för strategicresourcemanagement:persons:person.
...
Exempel
SearchPersonsForProfileByOrder
Request
Response
language | xml |
---|
Request | Response |
---|---|
searchPersonsByFile Version 1 curl -X POST \ Statuskod: 201 CREATED { * Filen är inte av typ CSV * Filen är tom * De första raderna innehåller ogiltigt formaterad data * Den angivna profilen är inte giltig * Det angivna värdet för max antal personposter per fil är för lågt Statuskod: 401 UNAUTHORIZED * Konsumenten saknar behörighet till tjänstenStatuskod: 500 INTERNAL SERVER ERROR * Internt oförutsett fel * Filens storlek i MB överskrider tillåten gräns * Felaktig datatyp angiven för parameter |
Hämta resultat för personsök
Flödet startar med att ett urval för ett stort antal patienter behöver göras. Detta urval sker genom anrop till någon av de asynkron "*ByOrder-tjänsterna" eller SearchPersonsByFile som alla returnerar ett Order-Id.
Fråga | Svar |
---|---|
Detta Order-Id används sedan som inparameter till tjänsten GetFilesForOrderId som returnerar ett svar med en eller flera länkar till resultatfilerna.
Fråga | Svar |
---|---|
Då ordnarna som inkommer via dessa asynkrona tjänster läggs på kö så är det inte säkert att resultatet är färdigt ifall man frågar direkt efter att ordern har lagts. Tiden för orderna att bli klar varierar beroende på last på systemet och storleken på resultatet. Ett frågande system bör dock kunna förvänta sig ett svar inom fyra timmar.
Under tiden ordern inte är klar returnerar GetFilesForOrderId ett svar utan länkar/<multimedia>-stycke.
...
searchPersonsByFile Version 2 curl -X POST \ | Statuskod: 201 CREATED { Statuskod: 400 BAD_REQUEST
|
För att hämta resultatet av sökningen, följ flödet i avsnittet “Hämta resultatet för asynkron personsökning” nedan.
Hämta resultatet för asynkron personsökning
Flödet startar med att ett urval för ett stort antal personer behöver göras. Detta urval sker genom anrop till någon av tjänstekontrakten SearchPersonsForProfileByOrder(Unrestricted) (SOAP) eller någon av REST-tjänsterna searchPersonsByFile/getPersonsByFile som alla returnerar ett Order-Id.
Fråga | Svar |
---|---|
Detta Order-Id används sedan som inparameter till tjänstekontraktet GetFilesForOrderId (SOAP) som returnerar ett svar med en eller flera länkar till resultatfilerna.
Fråga | Svar |
---|---|
Då de orders som inkommer via dessa asynkrona tjänster läggs på kö så är det inte säkert att resultatet är färdigt ifall man frågar direkt efter att ordern har lagts. Tiden för orderna att bli klar varierar beroende på last på systemet och storleken på resultatet. Ett frågande system bör dock kunna förvänta sig ett svar inom fyra timmar.
Under tiden ordern inte är klar returnerar GetFilesForOrderId ett svar utan länkar/<multimedia>-stycke.
Resultatfilerna är garanterat tillgängliga i ett dygn. Därefter rensas dom automatiskt bort. Filen kan bara hämtas en gång då de efter hämtning rensas bort.
Resultatfilerna är ZIP:ade och innehåller en XML-fil med det urval som efterfrågats. Formatet som specificeras i TKB och XSD för strategicresourcemanagement:persons:person.
...
Begränsning i antal sökträffar: Av prestandaskäl begränsas sökningar via SearchPersonsForProfileByOrder(Unrestricted) till maximalt 250.000 sökträffar. |
---|
Exempel
SearchPersonsForProfileByOrder
Request | Response | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
|
|
GetFilesForOrderId
Request | Response | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Resultat ej klart:
Resultat klart:
|
REST
Request
Response
https://api.pu.ineratest.org:443/purest/order/get/fd6a78ee-da71-4ec6-a099-cbccc21fe468
Statuskod: 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="<filnamn>"
Transfer-Encoding: chunked
Content: fil (zippat xmldata enligt strategicresourcemanagement:persons:person)
Struktur för filnamn (både ZIP och XML): <orderId>_<datum>_<löpnummer>.zip (samt .xml)
Exempel: 0622-TO17-09215997_20170622_1.zip
* Ogiltig context path
* HSA-id för konsument saknas
* Certifikat för OrderId matchar inte certifikat som används vid hämtning av fil
* Filen har redan hämtats
Statuskod: 401 UNAUTHORIZED
* Konsumenten saknar behörighet till tjänstenStatuskod: 404 NOT FOUND
* Begärd referens (GUID) existerar inte
Statuskod: 500 INTERNAL SERVER ERROR
* Internt oförutsätt fel
|
Filnedladdning via order/get (REST)
Request | Response |
---|---|
https://api.pu.ineratest.org:443/purest/order/get/fd6a78ee-da71-4ec6-a099-cbccc21fe468 | Statuskod: 200 OK Struktur för filnamn (både ZIP och XML): <orderId>_<datum>_<löpnummer>.zip (samt .xml) Statuskod: 400 BAD_REQUEST Statuskod: 404 NOT FOUND |
Avvikande namespace-hantering i domänversion 4
I personuppgiftstjänstens domänversion 4 kommer svarsfilerna som genereras av SearchPersonsByFile v2 samt SearchPersonsForProfileByOrder(Unrestricted) v4 att göra namespace-deklarationer på ett avvikande sätt, vilket kan göra att inläsning/parsning av dessa filer misslyckas. Detta kan hanteras genom search-and-replace i svarsfilerna enligt arbetsstegen som redovisas nedan, innan inläsning görs.
Avvikelsen kommer inte att korrigeras i domänversion 4 för att inte påverka de kunder som redan byggt fungerande integrationer. Denna avvikelse återfinns inte från och med domänversion 5.
Expandera | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
Ersätt:
Mot tex:
Ersätt:
Mot tex:
Ersätt:
mot:
|
Bilagor för reservidentitet
En reservidentitet kan i PU-tjänsten ha 0..n bilagor. Dessa används för att styrka identiteten och kan vara exempelvis en kopia på ett pass. Bilagan kan laddas upp till reservidentiteten och senare kopplas till en specifik uppgift om styrkande av identitet. All operationer gällande bilagor görs med fördel i det av PU-tjänsten tillhandahålla GUI't, men kan vid behov hanteras av integrerande tjänster. För hantering av bilagor via GUI hänvisas till Användarhanboken för PU. Nedan beskrivs de flöden som appliceras vid integration av konsument.
Enbart exempel för REST-tjänster redovisas i följande kapitel. För information om användandet av RIV-tjänsterna hänvisas till TKB.
Ladda upp bilaga
Uppladdning av bilaga sker genom PUT och föregås av en hämtning av personpost för aktuell reservidentitet. Detta för att säkerställa att identiteten finns.
...
URL
Beror på miljö, men exempelvis: https://api.pu.ineratest.org:443/purest/attachment/put
Parametrar
Namn | Beskrivning |
---|---|
actorRoot | root (OID) för aktör |
actorExtension | värde för aktör |
actorProfessionalRoot | root (OID) för aktörens organisation/vårdgivare |
actorProfessionalExtension | värde för aktörens organisation/vårdgivare |
patientRoot | root (OID) för patientidentitet |
patientExtension | värde patientidentitet |
file | bilagan |
Exempel
Via cURL
Request | Response |
---|---|
curl -X PUT \ | Statuskod: 200 OK { Statuskod: 400 BAD_REQUEST
|
Koppla / Koppla ifrån bilaga
Dessa operationer är rena RIV-tjänster och beskrivs i TKB.
...
Hämta bilaga
Bilagor erhålls som en referens-URL i svaret från PU-tjänstens. Dessa används sedan som GET anrop för att hämta filerna.
...
URL
Beror på miljö, men exempelvis: https://api.pu.ineratest.org:443/purest/attachment/get/e870cddb-5842-4c72-a804-7d39fa4c5478
Parametrar
Bilagans referensID som en del av URL
Exempel
Via cURL
Request | Response |
---|---|
curl -X GET \ | Statuskod: 200 OK Statuskod: 400 BAD_REQUEST Statuskod: 404 NOT FOUND |
Ta bort bilaga
Flödet förutsätter att bilagan inte har kvar några kopplingar inom reservidentiteten. Dvs flöde för "koppla ifrån bilaga" måste genomföras då det är applicerbart.
...
URL
Beror på miljö, men exempelvis: https://api.pu.ineratest.org:443/purest/attachment/delete
Parametrar
Namn | Beskrivning |
---|---|
actorRoot | root (OID) för aktör |
actorExtension | värde för aktör |
actorProfessionalRoot | root (OID) för aktörens organisation/vårsgivare |
actorProfessionalExtension | värde för aktörens organisation/vårsgivare |
patientRoot | root (OID) för patientidentitet |
patientExtension | värde patientidentitet |
referenceId | bilagans id |
Exempel
Via cURL.
Request | Response |
---|---|
curl -X DELETE \ | Statuskod: 200 OK File with id: e870cddb-5842-4c72-a804-7d39fa4c5478 was successfully deleted. Statuskod: 400 BAD_REQUEST Statuskod: 404 NOT FOUND |
...