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) är enbart tillgänglig genom direktaccess mot tjänsteproducent.
Image Added 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.
Behörighet
Vid användandet av REST-tjänster i Personuppgiftstjänsten måste man vara upplagd som webservice-klient direkt i Personuppgiftstjänsten. Därför måste samtliga system, förutom att bli anslutna till NTjP för t.ex SearchPersonsForProfileByOrder och/eller GetFilesForOrderId även kontakta Ineras kundtjänst på kundservice@inera.se med information i listan nedan. Detta är inte nödvändigtvis samma systemid som är anslutet till NTJP (som t ex kan vara en regional tjänsteplattform) utan det HSA-id som återfinns i http headern x-rivta-original-serviceconsumer-hsaid i enlighet med RIVTA Regel 23 samt "Bevara ursprunglig avsändares identitet i http header", original sender i bild ovan.
Mejlet ska innehålla följande värden:
Miljö: Test/Prod
REST-tjänst(er) man önskar ansluta till.
Det anslutande systemets HSA-id, original sender i bild ovan: <SE...>
Systemnamn: <..>
Kontaktuppgifter: <endast funktionsbrevlåda vid produktionsanslutning>
Tidigare ärendenummer för NTjP anslutningen ("Beställning från Beställningsstödet"): <...>
För att säkerställa att det är samma system som hämtar resultatfilen som gjorde sökningen så matchas HSA-id i certifikatet som användes vid sökningen (med det i filhämtningen (se bild i stycket ovan). Då själva sökningen skall göras via NTjP så används headern x-rivta-originalserviceconsumer-hsaid för att i tjänsten ta reda på vilken konsument som låg bakom anropet. Görs anropet dessutom genom en RTjP är det alltså viktigt att den regionala tjänsteplattformen populerar denna header (som ska förbli densamma genom NTjP ifall den redan existerar).
Användningsfall
Filhantering förekommer för två olika användningsfall inom PU-tjänsten.
Söka personuppgifter via fil
Hämta resultat för asynkron personsökning: SearchPersonsForProfileByOrder och Söka personuppgifter via fil.
Hämta, ladda upp samt ta bort bilagor för reservidentitet
Användningsfall 1 och 2 följer flödet enligt ARK_0038 (både SOAP och REST), medans användningsfall(en) för bilagor och filsök ej har behov av den listande SOAP-tjänsten. Flöden för samtliga användningsfall specificeras i följande kapitel.
Söka personuppgifter via fil
Ny funktion från version 4.6
Funktionen 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 REST-metoden SearchPersonsByFile 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. Formatet är densamma som i GetPersonsForProfileResponse. Det innebär att varje efterfrågad personpost kommer med ett stycke för RequestedPersonalIdentity men endast ifall personposten hittas i databasen så levereras stycket PersonRecord. Sekretessmarkerade personuppgifter hanteras som i GetPersonsForProfile med endast ett fåtal uppgifter på returnerade sekretessflaggade personposter.
Observera
title
Kommande förändring
Efter release av denna funktionalitet så upptäcktes att vid användande av parametern fromDate så returneras ändå stycket RequestedPersonalIdentity för de poster som inte har förändrats. Det är förstås inte önskvärt och kommer att förändras i nästa release.
Image Added
Image Added
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.
Datatyp: String.
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.
Datatyp: LocalDateTime.
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.
Datatyp: Integer.
Exempel: 1000
primaryidentity
Valfri parameter som om satt kommer endast personposter som är huvudidentitet inkluderas i svaret.
Statuskod: 201 CREATED Content-Type: application/json; charset=ISO-8859-1 Transfer-Encoding: chunked Content:
{ "orderId": "1028-TO63-15133551" }
Statuskod: 400 BAD_REQUEST * 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änsten
Statuskod: 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
Image Added
Image Added
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
Image Added
Image Added
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.
Image Added
OBS: 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.
Image Added
Exempel
SearchPersonsForProfileByOrder
Request
Response
Kodblock
language
xml
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:urn="urn:riv:itintegration:registry:1"
xmlns:urn1="urn:riv:strategicresourcemanagement:persons:person:SearchPersonsForProfileByOrderResponder:3">
<soapenv:Header>
<urn:LogicalAddress>SE165565594230-1000</urn:LogicalAddress>
</soapenv:Header>
<soapenv:Body>
<urn1:SearchPersonsForProfileByOrder>
<urn1:query>FROM personrecord WHERE name.givenname LIKE 'Daniel%';</urn1:query>
<urn1:queryLanguage>SimpleQL</urn1:queryLanguage>
<urn1:profile>P5</urn1:profile>
</urn1:SearchPersonsForProfileByOrder>
</soapenv:Body>
</soapenv:Envelope>
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
Statuskod: 400 BAD_REQUEST * 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änsten
Statuskod: 404 NOT FOUND * Begärd referens (GUID) existerar inte
Statuskod: 500 INTERNAL SERVER ERROR * Internt oförutsätt fel
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 eller POST och föregås av en hämtning av personpost för aktuell reservidentitet. Detta för att säkerställa att identiteten finns.
Image Added
URL
Beror på miljö, men exempelvis: https://ws.pu.ineratest.org:443/purest/attachment/put
Statuskod: 401 UNAUTHORIZED * Konsumenten saknar behörighet till tjänsten
Statuskod: 404 NOT FOUND * Begärd referens (GUID) existerar inte
Statuskod: 500 INTERNAL SERVER ERROR * Internt oförutsätt fel
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.
Image Added
URL
Beror på miljö, men exempelvis: https://ws.pu.ineratest.org:443/purest/attachment/delete