Innehåll

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) är enbart tillgänglig genom direktaccess mot tjänsteproducent.

Versionshantering av searchPersonsByFile i version 4.8

I version 4.8 gjordes en driftsförändring som gav REST-tjänsten för searchPersonsByFile två versioner. Läs mer under 2.1.1.2 Version

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 i följande användningsfall inom Personuppgiftstjänsten:

Söka personuppgifter via fil: SearchPersonsByFile
Hämta resultat för asynkron personsökning: SearchPersonsForProfileByOrder och SearchPersonsByFile
Hämta, ladda upp samt ta bort bilagor för reservidentitet

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 kapitel.

Söka personuppgifter via fil: SearchPersonsByFile

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, 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 testmiljö kallas testpersoner och i produktionsmiljö kallas valideringspersoner. En sökning mot sådan identitet kommer inte att returnera någon RequestedPersonRecord oavsett om personposten finns i databasen eller ej. För tester av SearchPersonsByFile 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. 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. Datatyp: Boolean. Exempel: true

Version

REST-tjänsten SearchPersonsByFile finns i två versioner och anropas via två olika url:er. Det som skiljer versionerna åt är att de är kompatibla med olika versioner av domänen strategicresourcemanagement:persons:person.

Exempel

Via cURL

Request

Response

Version 1

curl -X POST \
https://api.pu.ineratest.org:443/purest/searchPersonsByFile \
-H 'content-type: multipart/form-data;' \
-F profile=P1 \
-F fromDate=2021-10-12T00:00:00 \
-F maxResultsPerFile=1000 \
-F primaryidentity=true \
-F file=@bilagan.csv

Version 2

curl -X POST \
https://api.pu.ineratest.org:443/purest/v2/searchPersonsByFile \
-H 'content-type: multipart/form-data;' \
-F profile=P1 \
-F fromDate=2021-10-12T00:00:00 \
-F maxResultsPerFile=1000 \
-F primaryidentity=true \
-F file=@bilagan.csv

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

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.

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.

Exempel

SearchPersonsForProfileByOrder

Request

Response

<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>

<S:Envelope
 xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:SearchPersonsForProfileByOrderResponse
     xmlns:ns2="urn:riv:strategicresourcemanagement:persons:person:SearchPersonsForProfileByOrderResponder:3"
     xmlns:ns3="urn:riv:strategicresourcemanagement:persons:person:3"
     xmlns:ns4="urn:riv:itintegration:registry:1">
      <ns2:orderId>0622-TO17-09215997</ns2:orderId>
    </ns2:SearchPersonsForProfileByOrderResponse>
  </S:Body>
</S:Envelope>

GetFilesForOrderId

Request

Response

<soapenv:Envelope
 xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:urn="urn:riv:itintegration:registry:1"
 xmlns:urn1="urn:riv:strategicresourcemanagement:persons:person:GetFilesForOrderIdResponder:3">
  <soapenv:Header>
    <urn:LogicalAddress>SE165565594230-1000</urn:LogicalAddress>
  </soapenv:Header>
  <soapenv:Body>
    <urn1:GetFilesForOrderId>
      <urn1:orderId>0622-TO17-09215997</urn1:orderId>
    </urn1:GetFilesForOrderId>
  </soapenv:Body>
</soapenv:Envelope>

Resultat ej klart:

<S:Envelope
 xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:GetFilesForOrderIdResponse
     xmlns:ns2="urn:riv:strategicresourcemanagement:persons:person:GetFilesForOrderIdResponder:3"
     xmlns:ns3="urn:riv:strategicresourcemanagement:persons:person:3"
     xmlns:ns4="urn:riv:itintegration:registry:1">
    </ns2:GetFilesForOrderIdResponse>
  </S:Body>
</S:Envelope>

Resultat klart:

<S:Envelope
 xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:GetFilesForOrderIdResponse
     xmlns:ns2="urn:riv:strategicresourcemanagement:persons:person:GetFilesForOrderIdResponder:3"
     xmlns:ns3="urn:riv:strategicresourcemanagement:persons:person:3"
     xmlns:ns4="urn:riv:itintegration:registry:1">
      <ns2:multimedia>
        <ns3:mediaType>application/zip</ns3:mediaType>
        <ns3:reference>https://api.pu.ineratest.org:443/purest/order/get/fd6a78ee-da71-4ec6-a099-cbccc21fe468</ns3:reference>
      </ns2:multimedia>
    </ns2:GetFilesForOrderIdResponse>
  </S:Body>
</S:Envelope>

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

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 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 \
https://api.pu.ineratest.org:443/purest/attachment/put \
-H 'content-type: multipart/form-data; \
-F actorRoot=HSAID \
-F actorExtension=SE123456789 \
-F actorProfessionalRoot=HSAID \
-F actorProfessionalExtension=SE987654321 \
-F patientRoot=1.2.752.74.9.1 \
-F patientExtension=00002040AA11 \
-F file=@bilagan.jpg

Statuskod: 200 OK
Content-Type: application/json; charset=ISO-8859-1
Transfer-Encoding: chunked
Content:

{
"id": "36a7068d-172b-4fee-bed5-13ecbdfa7ff2",
"mediaType": "image/jpeg",
"value": null,
"reference": "https://api.pu.ineratest.org:443/purest/attachment/get/36a7068d-172b-4fee-bed5-13ecbdfa7ff2"
}

Statuskod: 400 BAD_REQUEST
* Ogiltig context path
* HSA-id för konsument saknas
* Ogiltig patientidentitet / parametrar

Statuskod: 401 UNAUTHORIZED
* Konsumenten saknar behörighet till tjänsten

Statuskod: 500 INTERNAL SERVER ERROR
* Internt oförutsätt fel

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 \
https://api.pu.ineratest.org:443/purest/attachment/get/e870cddb-5842-4c72-a804-7d39fa4c5478

Statuskod: 200 OK
Content-Type: <aktuell MIME-type>
Content-Disposition: attachment; filename="<filnamn>"
Transfer-Encoding: chunked
Content: filen

Statuskod: 400 BAD_REQUEST
* Ogiltig context path
* HSA-id för konsument saknas

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.

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 \
https://api.pu.ineratest.org:443/purest/attachment/delete \
-H 'content-type: multipart/form-data; \
-F actorRoot=HSAID \
-F actorExtension=SE123456789 \
-F actorProfessionalRoot=HSAID \
-F actorProfessionalExtension=SE987654321 \
-F patientRoot=1.2.752.74.9.1 \
-F patientExtension=00002040AA11 \
-F referenceId=e870cddb-5842-4c72-a804-7d39fa4c5478

Statuskod: 200 OK
Content-Type: text/plain; charset=iso-8859-1
Transfer-Encoding: chunked
Content:

File with id: e870cddb-5842-4c72-a804-7d39fa4c5478 was successfully deleted.

Statuskod: 400 BAD_REQUEST
* Ogiltig context path
* HSA-id för konsument saknas
* Ogiltig patientidentitet / parametrar

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örutsett fel

Dokumentation

För mer detaljer kring tjänstekontrakten se tjänstekontraktsbeskrivningen för domänen strategicresourcemanagement:persons:person

Se: http://rivta.se/domains/strategicresourcemanagement_persons_person.html

Webbläsaren stöds inte